@teachinglab/omd 0.1.0

package/canvas/utils/mathUtils.js

@@ -0,0 +1,259 @@
+export class mathUtils {
+    /**
+     * Calculate distance between two points
+     * @param {Object} p1 - First point {x, y}
+     * @param {Object} p2 - Second point {x, y}
+     * @returns {number} Distance
+     */
+    static distance(p1, p2) {
+        const dx = p2.x - p1.x;
+        const dy = p2.y - p1.y;
+        return Math.sqrt(dx * dx + dy * dy);
+    }
+    
+    /**
+     * Calculate squared distance (faster than distance when just comparing)
+     * @param {Object} p1 - First point {x, y}
+     * @param {Object} p2 - Second point {x, y}
+     * @returns {number} Squared distance
+     */
+    static distanceSquared(p1, p2) {
+        const dx = p2.x - p1.x;
+        const dy = p2.y - p1.y;
+        return dx * dx + dy * dy;
+    }
+    
+    /**
+     * Calculate angle between two points
+     * @param {Object} p1 - First point {x, y}
+     * @param {Object} p2 - Second point {x, y}
+     * @returns {number} Angle in radians
+     */
+    static angle(p1, p2) {
+        return Math.atan2(p2.y - p1.y, p2.x - p1.x);
+    }
+    
+    /**
+     * Calculate angle in degrees
+     * @param {Object} p1 - First point {x, y}
+     * @param {Object} p2 - Second point {x, y}
+     * @returns {number} Angle in degrees
+     */
+    static angleDegrees(p1, p2) {
+        return this.angle(p1, p2) * 180 / Math.PI;
+    }
+    
+    /**
+     * Linear interpolation between two values
+     * @param {number} a - Start value
+     * @param {number} b - End value
+     * @param {number} t - Interpolation factor (0-1)
+     * @returns {number} Interpolated value
+     */
+    static lerp(a, b, t) {
+        return a + (b - a) * t;
+    }
+    
+    /**
+     * Linear interpolation between two points
+     * @param {Object} p1 - Start point {x, y}
+     * @param {Object} p2 - End point {x, y}
+     * @param {number} t - Interpolation factor (0-1)
+     * @returns {Object} Interpolated point {x, y}
+     */
+    static lerpPoint(p1, p2, t) {
+        return {
+            x: this.lerp(p1.x, p2.x, t),
+            y: this.lerp(p1.y, p2.y, t)
+        };
+    }
+    
+    /**
+     * Clamp value between min and max
+     * @param {number} value - Value to clamp
+     * @param {number} min - Minimum value
+     * @param {number} max - Maximum value
+     * @returns {number} Clamped value
+     */
+    static clamp(value, min, max) {
+        return Math.min(Math.max(value, min), max);
+    }
+    
+    /**
+     * Normalize value from one range to another
+     * @param {number} value - Input value
+     * @param {number} inMin - Input range minimum
+     * @param {number} inMax - Input range maximum
+     * @param {number} outMin - Output range minimum
+     * @param {number} outMax - Output range maximum
+     * @returns {number} Normalized value
+     */
+    static map(value, inMin, inMax, outMin, outMax) {
+        return (value - inMin) * (outMax - outMin) / (inMax - inMin) + outMin;
+    }
+    
+    /**
+     * Calculate distance from point to line segment
+     * @param {Object} point - Point {x, y}
+     * @param {Object} lineStart - Line start {x, y}
+     * @param {Object} lineEnd - Line end {x, y}
+     * @returns {number} Distance
+     */
+    static distanceToLineSegment(point, lineStart, lineEnd) {
+        const dx = lineEnd.x - lineStart.x;
+        const dy = lineEnd.y - lineStart.y;
+        const length = Math.sqrt(dx * dx + dy * dy);
+        
+        if (length === 0) {
+            return this.distance(point, lineStart);
+        }
+        
+        const t = Math.max(0, Math.min(1, ((point.x - lineStart.x) * dx + (point.y - lineStart.y) * dy) / (length * length)));
+        const projection = {
+            x: lineStart.x + t * dx,
+            y: lineStart.y + t * dy
+        };
+        
+        return this.distance(point, projection);
+    }
+    
+    /**
+     * Check if point is inside circle
+     * @param {Object} point - Point {x, y}
+     * @param {Object} center - Circle center {x, y}
+     * @param {number} radius - Circle radius
+     * @returns {boolean} True if point is inside circle
+     */
+    static pointInCircle(point, center, radius) {
+        return this.distanceSquared(point, center) <= radius * radius;
+    }
+    
+    /**
+     * Check if point is inside rectangle
+     * @param {Object} point - Point {x, y}
+     * @param {Object} rect - Rectangle {x, y, width, height}
+     * @returns {boolean} True if point is inside rectangle
+     */
+    static pointInRect(point, rect) {
+        return point.x >= rect.x && 
+               point.x <= rect.x + rect.width &&
+               point.y >= rect.y && 
+               point.y <= rect.y + rect.height;
+    }
+    
+    /**
+     * Smooth an array of points using averaging
+     * @param {Array} points - Array of points
+     * @param {number} factor - Smoothing factor (0-1)
+     * @returns {Array} Smoothed points
+     */
+    static smoothPoints(points, factor = 0.5) {
+        if (points.length < 3) return points;
+        
+        const smoothed = [points[0]]; // Keep first point
+        
+        for (let i = 1; i < points.length - 1; i++) {
+            const prev = points[i - 1];
+            const curr = points[i];
+            const next = points[i + 1];
+            
+            const avgX = (prev.x + curr.x + next.x) / 3;
+            const avgY = (prev.y + curr.y + next.y) / 3;
+            
+            smoothed.push({
+                x: this.lerp(curr.x, avgX, factor),
+                y: this.lerp(curr.y, avgY, factor),
+                ...curr // Preserve other properties
+            });
+        }
+        
+        smoothed.push(points[points.length - 1]); // Keep last point
+        return smoothed;
+    }
+    
+    /**
+     * Generate bezier curve points
+     * @param {Object} p0 - Control point 0
+     * @param {Object} p1 - Control point 1
+     * @param {Object} p2 - Control point 2
+     * @param {Object} p3 - Control point 3
+     * @param {number} steps - Number of steps
+     * @returns {Array} Curve points
+     */
+    static bezierCurve(p0, p1, p2, p3, steps = 20) {
+        const points = [];
+        
+        for (let i = 0; i <= steps; i++) {
+            const t = i / steps;
+            const u = 1 - t;
+            const tt = t * t;
+            const uu = u * u;
+            const uuu = uu * u;
+            const ttt = tt * t;
+            
+            const x = uuu * p0.x + 3 * uu * t * p1.x + 3 * u * tt * p2.x + ttt * p3.x;
+            const y = uuu * p0.y + 3 * uu * t * p1.y + 3 * u * tt * p2.y + ttt * p3.y;
+            
+            points.push({ x, y });
+        }
+        
+        return points;
+    }
+    
+    /**
+     * Convert degrees to radians
+     * @param {number} degrees - Angle in degrees
+     * @returns {number} Angle in radians
+     */
+    static degreesToRadians(degrees) {
+        return degrees * Math.PI / 180;
+    }
+    
+    /**
+     * Convert radians to degrees
+     * @param {number} radians - Angle in radians
+     * @returns {number} Angle in degrees
+     */
+    static radiansToDegrees(radians) {
+        return radians * 180 / Math.PI;
+    }
+    
+    /**
+     * Rotate point around center
+     * @param {Object} point - Point to rotate {x, y}
+     * @param {Object} center - Center of rotation {x, y}
+     * @param {number} angle - Rotation angle in radians
+     * @returns {Object} Rotated point {x, y}
+     */
+    static rotatePoint(point, center, angle) {
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        const dx = point.x - center.x;
+        const dy = point.y - center.y;
+        
+        return {
+            x: center.x + dx * cos - dy * sin,
+            y: center.y + dx * sin + dy * cos
+        };
+    }
+    
+    /**
+     * Generate random number between min and max
+     * @param {number} min - Minimum value
+     * @param {number} max - Maximum value
+     * @returns {number} Random number
+     */
+    static random(min, max) {
+        return Math.random() * (max - min) + min;
+    }
+    
+    /**
+     * Generate random integer between min and max
+     * @param {number} min - Minimum value (inclusive)
+     * @param {number} max - Maximum value (inclusive)
+     * @returns {number} Random integer
+     */
+    static randomInt(min, max) {
+        return Math.floor(Math.random() * (max - min + 1)) + min;
+    }
+} 

package/docs/api/configuration-options.md

@@ -0,0 +1,104 @@
+# Configuration Options
+
+This document details all available configuration options for the OMD library, managed by the `omdConfigManager` module. These options allow you to customize various aspects of the library's behavior, appearance, and mathematical preferences.
+
+## Overview
+
+The OMD configuration is a single JavaScript object that can be loaded from a JSON file or set programmatically. It is organized into logical categories.
+
+## Default Configuration Structure
+
+If no custom configuration is provided, the library uses the following default structure:
+
+```json
+{
+    "multiplication": {
+        "symbol": "·",
+        "forceImplicit": false,
+        "implicitCombinations": {
+            "constantVariable": true,
+            "variableConstant": false,
+            "parenthesisAfterVariable": true,
+            "parenthesisAfterConstant": true,
+            "variableParenthesis": true,
+            "parenthesisParenthesis": true,
+            "parenthesisVariable": true,
+            "parenthesisConstant": true,
+            "variableVariable": true
+        }
+    },
+    "stepVisualizer": {
+        "dotSizes": {
+            "level0": 8,
+            "level1": 6,
+            "level2": 4
+        },
+        "fontWeights": {
+            "level0": 400,
+            "level1": 300,
+            "level2": 200
+        }
+    }
+}
+```
+
+## Configuration Categories and Options
+
+### `multiplication`
+
+Settings related to how multiplication is displayed and handled.
+
+-   **`symbol`** {string}
+    -   The character used to represent multiplication. Default: `"·"` (middle dot).
+    -   Example: `"*"` or `"×"`.
+
+-   **`forceImplicit`** {boolean}
+    -   If `true`, implicit multiplication (e.g., `2x` instead of `2 * x`) is always used where mathematically valid, overriding `implicitCombinations`.
+    -   Default: `false`.
+
+-   **`implicitCombinations`** {Object}
+    -   An object defining specific scenarios where implicit multiplication should be used. Each property is a boolean.
+    -   **`constantVariable`** {boolean}: `2x` (Default: `true`)
+    -   **`variableConstant`** {boolean}: `x2` (Default: `false`)
+    -   **`parenthesisAfterVariable`** {boolean}: `x(y+z)` (Default: `true`)
+    -   **`parenthesisAfterConstant`** {boolean}: `2(x+y)` (Default: `true`)
+    -   **`variableParenthesis`** {boolean}: `(x+y)z` (Default: `true`)
+    -   **`parenthesisParenthesis`** {boolean}: `(x+y)(a+b)` (Default: `true`)
+    -   **`parenthesisVariable`** {boolean}: `(x+y)z` (Default: `true`)
+    -   **`parenthesisConstant`** {boolean}: `(x+y)2` (Default: `true`)
+    -   **`variableVariable`** {boolean}: `xy` (Default: `true`)
+
+### `stepVisualizer`
+
+Settings specific to the `omdStepVisualizer` component, controlling the appearance of step dots and text.
+
+-   **`dotSizes`** {Object}
+    -   Defines the radius of the step dots based on their importance level.
+    -   **`level0`** {number}: Radius for major steps. Default: `8`.
+    -   **`level1`** {number}: Radius for minor steps. Default: `6`.
+    -   **`level2`** {number}: Radius for detailed steps. Default: `4`.
+
+-   **`fontWeights`** {Object}
+    -   Defines the font weight for the equations based on their importance level.
+    -   **`level0`** {number}: Font weight for major steps. Default: `400`.
+    -   **`level1`** {number}: Font weight for minor steps. Default: `300`.
+    -   **`level2`** {number}: Font weight for detailed steps. Default: `200`.
+
+## Usage
+
+Configuration options can be set during initialization or updated at runtime using the `omdConfigManager` functions. For detailed usage, refer to the [`omdConfigManager`](./omdConfigManager.md) documentation.
+
+```javascript
+import { initializeConfig, setConfigValue, getConfigValue } from 'omd-library';
+
+// Initialize with a custom config file
+await initializeConfig('./my-custom-omd-config.json');
+
+// Or set options programmatically
+setConfigValue('multiplication.symbol', '*');
+setConfigValue('stepVisualizer.dotSizes.level0', 10);
+
+// Retrieve a config value
+const currentSymbol = getConfigValue('multiplication.symbol');
+console.log(currentSymbol); // Output: *
+```

package/docs/api/eventManager.md

@@ -0,0 +1,68 @@
+# EventManager
+
+The `EventManager` class is responsible for handling all user interactions with the canvas, including pointer events (mouse, touch, pen), keyboard events, and wheel events. It normals these events and delegates them to the appropriate handlers, such as the active tool or the `pointerEventHandler`.
+
+## Class Definition
+
+```javascript
+export class EventManager {
+    // ...
+}
+```
+
+## Constructor
+
+### `new EventManager(canvas)`
+
+Creates a new `EventManager` instance.
+
+*   **canvas** (`OMDCanvas`): The canvas instance.
+
+## Public Methods
+
+### `initialize()`
+
+Initializes the event manager and attaches all necessary event listeners to the canvas and document.
+
+### `getPointerInfo()`
+
+Gets information about the current state of the pointers.
+
+*   **Returns**: `object` - An object containing pointer information, including the number of active pointers and whether the user is currently drawing.
+
+### `destroy()`
+
+Destroys the event manager and removes all event listeners.
+
+## Event Handling
+
+The `EventManager` listens for the following events:
+
+*   **Pointer Events**: `pointerdown`, `pointermove`, `pointerup`, `pointercancel`, `pointerenter`, `pointerleave`
+*   **Keyboard Events**: `keydown`, `keyup`
+*   **Wheel Events**: `wheel`
+*   **Context Menu**: `contextmenu`
+
+When an event occurs, the `EventManager` normalizes it and then delegates it to the appropriate handler. For example, pointer events are passed to the `pointerEventHandler` and the active tool, while keyboard events are used to trigger global shortcuts or are passed to the active tool.
+
+## State Management
+
+The `EventManager` tracks the following state:
+
+*   **`activePointers`**: A map of all currently active pointers on the canvas.
+*   **`isDrawing`**: A boolean indicating whether a drawing operation is currently in progress.
+*   **`lastEventTime`**: The timestamp of the last processed event, used for throttling.
+
+## Event Emitters
+
+The `EventManager` also emits the following events on the canvas instance:
+
+*   `pointerDown`
+*   `pointerMove`
+*   `pointerUp`
+*   `pointerCancel`
+*   `pointerEnter`
+*   `pointerLeave`
+*   `keyDown`
+*   `keyUp`
+*   `wheel`

package/docs/api/focusFrameManager.md

@@ -0,0 +1,150 @@
+# FocusFrameManager
+
+The `FocusFrameManager` class is responsible for creating, managing, and capturing content from focus frames on the canvas.
+
+## Class Definition
+
+```javascript
+export class FocusFrameManager {
+    // ...
+}
+```
+
+## Constructor
+
+### `new FocusFrameManager(canvas)`
+
+Creates a new `FocusFrameManager` instance.
+
+*   **canvas** (`OMDCanvas`): The canvas instance.
+
+## Public Methods
+
+### `createFrame([options])`
+
+Creates a new focus frame.
+
+*   **[options]** (`object`, optional): Configuration options for the frame.
+    *   **x** (`number`, optional): The x-coordinate of the frame. Defaults to `0`.
+    *   **y** (`number`, optional): The y-coordinate of the frame. Defaults to `0`.
+    *   **width** (`number`, optional): The width of the frame. Defaults to `200`.
+    *   **height** (`number`, optional): The height of the frame. Defaults to `150`.
+    *   **showOutline** (`boolean`, optional): Whether to show the frame outline. Defaults to `true`.
+    *   **outlineColor** (`string`, optional): The color of the frame outline. Defaults to `'#007bff'`.
+    *   **outlineWidth** (`number`, optional): The width of the frame outline. Defaults to `2`.
+    *   **outlineDashed** (`boolean`, optional): Whether the frame outline is dashed. Defaults to `false`.
+*   **Returns**: `object` - An object containing the `id` and `frame` of the created frame.
+
+### `removeFrame(frameId)`
+
+Removes a focus frame.
+
+*   **frameId** (`string`): The ID of the frame to remove.
+*   **Returns**: `boolean` - `true` if the frame was removed, `false` otherwise.
+
+### `getFrame(frameId)`
+
+Gets a focus frame by its ID.
+
+*   **frameId** (`string`): The ID of the frame to get.
+*   **Returns**: `FocusFrame` or `undefined` - The frame instance, or `undefined` if not found.
+
+### `setActiveFrame(frameId)`
+
+Sets the active focus frame.
+
+*   **frameId** (`string`): The ID of the frame to set as active.
+*   **Returns**: `boolean` - `true` if the frame was set as active, `false` otherwise.
+
+### `getActiveFrame()`
+
+Gets the currently active focus frame.
+
+*   **Returns**: `FocusFrame` or `null` - The active frame, or `null` if no frame is active.
+
+### `captureActiveFrame()`
+
+Captures the content of the active focus frame as an SVG string.
+
+*   **Returns**: `string` or `null` - The SVG content of the active frame, or `null` if no frame is active.
+
+### `captureAllFrames()`
+
+Captures the content of all focus frames.
+
+*   **Returns**: `Map<string, string>` - A map of frame IDs to their SVG content.
+
+### `clearAllFrames()`
+
+Removes all focus frames from the canvas.
+
+### `getFrameIds()`
+
+Gets the IDs of all focus frames.
+
+*   **Returns**: `Array<string>` - An array of frame IDs.
+
+### `destroy()`
+
+Destroys the focus frame manager and all associated frames.
+
+# FocusFrame
+
+The `FocusFrame` class represents an individual focus frame on the canvas.
+
+## Class Definition
+
+```javascript
+class FocusFrame {
+    // ...
+}
+```
+
+## Public Methods
+
+### `setActive(active)`
+
+Sets the frame as active or inactive.
+
+*   **active** (`boolean`): Whether the frame should be active.
+
+### `capture()`
+
+Captures the content of the frame as an SVG string.
+
+*   **Returns**: `string` - The SVG content of the frame.
+
+### `toBitmap([format], [quality])`
+
+Converts the frame content to a bitmap.
+
+*   **[format]** (`string`, optional): The image format. Defaults to `'png'`.
+*   **[quality]** (`number`, optional): The image quality. Defaults to `1`.
+*   **Returns**: `Promise<Blob>` - A promise that resolves with the bitmap as a `Blob`.
+
+### `downloadAsBitmap([filename], [format])`
+
+Downloads the frame content as a bitmap image.
+
+*   **[filename]** (`string`, optional): The filename for the downloaded image. Defaults to `focus-frame-{id}.png`.
+*   **[format]** (`string`, optional): The image format. Defaults to `'png'`.
+
+### `updateBounds(bounds)`
+
+Updates the bounds of the frame.
+
+*   **bounds** (`object`): An object containing the new bounds.
+    *   **x** (`number`, optional): The new x-coordinate.
+    *   **y** (`number`, optional): The new y-coordinate.
+    *   **width** (`number`, optional): The new width.
+    *   **height** (`number`, optional): The new height.
+
+### `getBounds()`
+
+Gets the bounds of the frame.
+
+*   **Returns**: `object` - An object containing the bounds of the frame.
+
+### `destroy()`
+
+Destroys the frame and removes it from the canvas.

package/docs/api/index.md

@@ -0,0 +1,91 @@
+# OMD Library Entry Point
+
+This module (`omd/index.js`) serves as the main entry point for the OMD (Open Math Display) library. It re-exports all core classes, visualization components, and utility functions, making them easily accessible from a single import.
+
+## Overview
+
+When you import from `omd-library` (or directly from `omd/index.js`), you gain access to a comprehensive set of tools for building and manipulating mathematical expressions and their visual representations.
+
+## Exports
+
+### Core Node Classes
+
+All classes extending `omdNode` are re-exported, allowing you to construct and work with various types of mathematical expressions:
+
+- [`omdNode`](./omdNode.md)
+- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md)
+- [`omdConstantNode`](./omdConstantNode.md)
+- [`omdEquationNode`](./omdEquationNode.md)
+- [`omdFunctionNode`](./omdFunctionNode.md)
+- [`omdGroupNode`](./omdGroupNode.md)
+- [`omdLeafNode`](./omdLeafNode.md)
+- [`omdOperationDisplayNode`](./omdOperationDisplayNode.md)
+- [`omdOperatorNode`](./omdOperatorNode.md)
+- [`omdParenthesisNode`](./omdParenthesisNode.md)
+- [`omdPowerNode`](./omdPowerNode.md)
+- [`omdRationalNode`](./omdRationalNode.md)
+- [`omdEquationSequenceNode`](./omdEquationSequenceNode.md)
+- [`omdSqrtNode`](./omdSqrtNode.md)
+- [`omdUnaryExpressionNode`](./omdUnaryExpressionNode.md)
+- [`omdVariableNode`](./omdVariableNode.md)
+
+### Visualization Components
+
+These classes provide high-level components for rendering and interacting with mathematical expressions:
+
+- [`omdStepVisualizer`](./omdStepVisualizer.md)
+- [`omdDisplay`](./omdDisplay.md)
+- [`omdCanvas`](./omdCanvas.md)
+- [`omdToolbar`](./omdToolbar.md)
+
+### Utilities
+
+Essential utility functions for parsing, simplification, and configuration management:
+
+- `getNodeForAST`: A factory function to get the correct `omdNode` class for a given math.js AST.
+- `simplifyStep`: Applies a single simplification step to an expression.
+- `initializeConfig`: Initializes the OMD configuration.
+- `setConfig`: Sets the OMD configuration.
+- `getDefaultConfig`: Retrieves the default OMD configuration.
+- `omdExpression`: (From `../src/omdExpression.js`) A base class for expressions.
+
+### `omdHelpers`
+
+A collection of convenience functions for common operations:
+
+#### `createNodeFromExpression(expression, mathjs)`
+- Creates an `omdNode` instance from a string expression using a provided math.js instance.
+
+#### `createEquation(equationString)`
+- Creates an `omdEquationNode` from a string representation of an equation.
+
+#### `createStepVisualizer(equationStrings)`
+- Creates an `omdStepVisualizer` instance from an array of equation strings.
+
+## Default Export
+
+The module also provides a default export, which is an object containing all the re-exported classes and functions, organized into logical groups (`nodes`, `helpers`, etc.). This allows for a more structured import if preferred.
+
+```javascript
+import OMD from 'omd-library';
+
+const equation = new omd.omdEquationNode(...);
+const display = new omd.omdDisplay(...);
+```
+
+## Example Usage
+
+```javascript
+import { omdDisplay, omdEquationNode, omdHelpers } from 'omd-library';
+
+// Create an equation using a helper
+const equation = omdHelpers.createEquation('2x + 5 = 15');
+
+// Create a display and render the equation
+const displayContainer = document.getElementById('math-container');
+const display = new omdDisplay(displayContainer);
+display.render(equation);
+
+// You can also directly access node classes
+const constant = new omdConstantNode({ value: 10 });
+```