@teachinglab/omd 0.1.0

package/docs/api/main.md

@@ -0,0 +1,58 @@
+# main.js - OMD Testing Environment
+
+This `main.js` file serves as the entry point for a testing environment designed to demonstrate the capabilities of the OMD (Open Math Display) library. It initializes the `omdDisplay` renderer, manages various UI elements, and provides functions for manipulating and visualizing mathematical expressions.
+
+## Core Functionality
+
+### Initialization
+
+Upon DOM content loading, the script initializes an `omdDisplay` instance, attaching it to the `renderPanel` element. It also sets up references to various UI elements (input fields, buttons, checkboxes) used for interaction.
+
+```javascript
+document.addEventListener('DOMContentLoaded', async () => {
+    const renderer = new omdDisplay(document.getElementById('renderPanel'), {
+        fontSize: 32,
+        centerContent: true,
+        topMargin: 40
+    });
+    // ... UI element setup ...
+});
+```
+
+### Expression Rendering
+
+The `renderExpression` function takes an expression from the `expressionInput` field, creates an `omdEquationStack` from it, and renders it using the `omdDisplay` instance.
+
+### Simplification
+
+The `simplify` function (and `simplifyAll`) applies simplification rules to the currently rendered equation sequence. It updates a history list with the simplification steps and messages.
+
+### Equation Operations
+
+Functions like `applyOperation` (for `+`, `-`, `*`, `/`) and `applyFunction` allow users to perform mathematical operations or apply functions to both sides of an equation. These operations modify the `omdEquationSequenceNode` and trigger re-rendering.
+
+### Expression Evaluation
+
+`evaluateExpression` takes an expression and optional variable assignments from the UI, then calls the library's evaluation method. The result is typically logged to the console.
+
+### Step Filtering
+
+`applyStepFilter` controls the visibility of simplification steps based on checkboxes (level 0, 1, 2), allowing users to focus on specific stages of the simplification process.
+
+### Event Listeners
+
+The script attaches event listeners to various UI buttons to trigger the corresponding functions (e.g., `renderButton` calls `renderExpression`, `simplifyButton` calls `simplify`).
+
+### Node Overlays (`window.demoOverlays`)
+
+A global `window.demoOverlays` object is exposed for demonstrating `omdNodeOverlay` functionality. It includes:
+
+*   **`hideLeft()`**: Hides the left side of the bottom-most equation in the sequence with an editable text overlay.
+*   **`hideRight()`**: Hides the right side of the bottom-most equation in the sequence with an editable text overlay.
+*   **`clearAll()`**: Recursively finds and destroys all `omdNodeOverlay` instances within the current equation sequence.
+
+These functions showcase how parts of a mathematical expression can be interactively covered or revealed, potentially for educational or problem-solving purposes.
+
+## Usage
+
+This `main.js` is intended to be used with an `index.html` file that provides the necessary UI elements (input fields, buttons, and a `renderPanel` div). Users can input mathematical expressions, apply operations, simplify, and observe the visual changes and step-by-step history.

package/docs/api/omdBinaryExpressionNode.md

@@ -0,0 +1,227 @@
+# omdBinaryExpressionNode
+
+Represents binary operations (addition, subtraction, multiplication, division) in mathematical expressions.
+
+## Class: `omdBinaryExpressionNode extends omdNode`
+
+```javascript
+import { omdBinaryExpressionNode } from './omd/nodes/omdBinaryExpressionNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdBinaryExpressionNode(ast)
+```
+
+**Parameters:**
+- `ast` {Object} - The AST node containing:
+  - `args`: Array of at least 2 operand AST nodes
+  - `op`: Operator symbol
+  - `implicit`: Optional boolean for implicit multiplication
+
+**Description:**
+Creates a node representing a binary operation like `a + b`, `x * y`, etc.
+
+### Properties
+
+Inherits all properties from [omdNode](./omdNode.md), plus:
+
+#### `left`
+- **Type:** [omdNode](./omdNode.md)
+- **Description:** The left operand node
+
+
+#### `operation`
+- **Type:** string
+- **Description:** The function name for the operation (e.g., 'add', 'multiply', 'subtract', 'divide').
+
+
+#### `op`
+- **Type:** [omdOperatorNode](./omdOperatorNode.md) | null
+- **Description:** The operator node (null for implicit multiplication). For multiplication, this may be removed and replaced with implicit multiplication based on configuration.
+
+
+#### `isImplicit`
+- **Type:** boolean
+- **Description:** Whether multiplication is implicit (e.g., `2x`). Determined by AST or configuration.
+
+#### `right`
+- **Type:** [omdNode](./omdNode.md)
+- **Description:** The right operand node
+
+### Methods
+
+Inherits all methods from [omdNode](./omdNode.md), plus:
+
+
+#### `parseOperation()`
+Internal method to extract the function name for the operation from the AST.
+- **Returns:** string - Function name (e.g., 'add', 'multiply', etc.)
+
+---
+
+
+#### `createExpressionNode(ast)`
+Internal method to create operand nodes.
+- `ast` {Object} - The AST for the operand
+- **Returns:** omdNode
+
+---
+
+
+#### `createOperatorNode(ast)`
+Internal method to create operator node.
+- `ast` {Object} - The AST with operator info
+- **Returns:** omdOperatorNode
+
+---
+
+#### `computeDimensions()`
+Calculates dimensions of expression.
+- Computes dimensions of all parts
+- Adds spacing between operator and operands
+- Sets total width and height
+
+---
+
+#### `updateLayout()`
+Updates positions of all elements.
+- Aligns operands and operator on baseline
+- Handles spacing for implicit multiplication
+
+---
+
+
+#### `getAlignmentBaseline()`
+Gets vertical alignment point.
+- **Returns:** number - Y-coordinate based on:
+  - Operator baseline if explicit
+  - Max child baseline if implicit
+
+---
+
+
+#### `clone()`
+Creates a deep clone of the expression.
+- **Returns:** omdBinaryExpressionNode - A new instance with:
+  - Cloned operands and operator
+  - Rebuilt argument list
+  - Copied AST data and operation
+  - Original node's ID added to provenance array
+
+---
+
+
+#### `getSpacing()`
+Gets horizontal spacing between elements.
+- **Returns:** number - 0 for implicit multiplication, otherwise scales with font size.
+
+---
+
+
+
+#### `_shouldUseImplicitMultiplication(left, right)` (internal)
+Internal method to check if multiplication should be implicit.
+- Based on configuration and operand types
+- **Returns:** boolean
+> Note: This method is intended for internal use and may change without notice.
+
+---
+
+
+#### `_shouldReorderMultiplication(left, right)` (internal)
+Internal method to check if operands should be reordered for coefficient multiplication (e.g., x*2 → 2*x).
+- **Returns:** boolean
+> Note: This method is intended for internal use and may change without notice.
+
+---
+
+
+#### `toMathJSNode()`
+Converts to math.js AST format.
+- **Returns:** Object - A math.js-compatible AST node with:
+  - `type`: "OperatorNode"
+  - `op`: Operator symbol
+  - `fn`: Function name
+  - `args`: Operand ASTs
+  - `implicit`: Boolean flag
+  - `id`: Node ID
+  - `provenance`: Provenance array
+
+---
+
+
+#### `toString()`
+Convert to string representation.
+- **Returns:** string - Format depends on operation. Handles implicit multiplication and adds parentheses as needed for precedence.
+
+---
+
+
+
+#### `evaluate(variables)`
+Evaluate the expression.
+- `variables` {Object} - Variable name to value mapping
+- **Returns:** number - The evaluated result
+- **Throws:** Error if division by zero is encountered or if the operation is unsupported.
+
+
+#### `needsParentheses()`
+Determines if parentheses are needed based on parent operator precedence.
+- **Returns:** boolean
+
+### Examples
+
+```javascript
+// Create from AST
+const node = new omdBinaryExpressionNode({
+  type: 'OperatorNode',
+  op: '+',
+  fn: 'add',
+  args: [
+    { type: 'SymbolNode', name: 'x' },
+    { type: 'ConstantNode', value: 2 }
+  ]
+});
+
+// Implicit multiplication
+const implicitMult = new omdBinaryExpressionNode({
+  type: 'OperatorNode',
+  op: '*',
+  fn: 'multiply',
+  args: [
+    { type: 'ConstantNode', value: 2 },
+    { type: 'SymbolNode', name: 'x' }
+  ],
+  implicit: true
+});
+
+// Division by zero (throws error)
+try {
+  const divByZero = new omdBinaryExpressionNode({
+    type: 'OperatorNode',
+    op: '/',
+    fn: 'divide',
+    args: [
+      { type: 'ConstantNode', value: 5 },
+      { type: 'ConstantNode', value: 0 }
+    ]
+  });
+  divByZero.evaluate();
+} catch (e) {
+  console.error('Error:', e.message); // Error: Division by zero.
+}
+
+// Render with proper spacing
+node.setFontSize(24);
+node.computeDimensions();
+node.updateLayout();
+```
+
+### See Also
+
+- [omdNode](./omdNode.md) - Parent class
+- [omdOperatorNode](./omdOperatorNode.md) - For operators
+- [omdConstantNode](./omdConstantNode.md) - For numeric operands
+- [omdVariableNode](./omdVariableNode.md) - For variable operands

package/docs/api/omdCanvas.md

@@ -0,0 +1,142 @@
+# omdCanvas
+
+The `omdCanvas` class is the core component for creating and managing a drawing canvas. It provides the primary interface for interacting with the canvas, including drawing, selecting, and managing strokes, as well as handling events and integrating with various tools and features.
+
+## Class Definition
+
+```javascript
+export class omdCanvas {
+    // ...
+}
+```
+
+## Constructor
+
+### `new omdCanvas(container, [options])`
+
+Creates a new `omdCanvas` instance.
+
+*   **container** (`HTMLElement` or `string`): The HTML element or a CSS selector string for the container where the canvas will be rendered.
+*   **[options]** (`object`, optional): Configuration options for the canvas. These options are passed to `CanvasConfig`.
+
+## Properties
+
+*   **container** (`HTMLElement`): The HTML container element for the canvas.
+*   **config** (`CanvasConfig`): The configuration object for the canvas.
+*   **svg** (`SVGElement`): The main SVG element representing the canvas.
+*   **backgroundLayer** (`SVGGElement`): The SVG group element for background elements (e.g., grid).
+*   **drawingLayer** (`SVGGElement`): The SVG group element for drawing strokes.
+*   **uiLayer** (`SVGGElement`): The SVG group element for UI elements (e.g., selection boxes).
+*   **focusFrameLayer** (`SVGGElement`): The SVG group element for focus frames.
+*   **strokes** (`Map<string, Stroke>`): A map of all strokes on the canvas, keyed by their ID.
+*   **selectedStrokes** (`Set<string>`): A set of IDs of currently selected strokes.
+*   **toolManager** (`ToolManager`): Manages the active drawing tools.
+*   **eventManager** (`EventManager`): Manages all user input events.
+*   **cursor** (`Cursor`): Manages the custom canvas cursor.
+*   **toolbar** (`Toolbar`): The canvas toolbar (if enabled).
+*   **focusFrameManager** (`FocusFrameManager`): Manages focus frames (if enabled).
+
+## Public Methods
+
+### `addStroke(stroke)`
+
+Adds a stroke to the canvas.
+
+*   **stroke** (`Stroke`): The stroke object to add.
+*   **Returns**: `string` - The ID of the added stroke.
+
+### `removeStroke(strokeId)`
+
+Removes a stroke from the canvas.
+
+*   **strokeId** (`string`): The ID of the stroke to remove.
+*   **Returns**: `boolean` - `true` if the stroke was removed, `false` otherwise.
+
+### `clear()`
+
+Clears all strokes from the canvas.
+
+### `selectStrokes(strokeIds)`
+
+Selects a set of strokes by their IDs.
+
+*   **strokeIds** (`Array<string>`): An array of stroke IDs to select.
+
+### `clientToSVG(clientX, clientY)`
+
+Converts client (screen) coordinates to SVG (canvas) coordinates.
+
+*   **clientX** (`number`): The client X coordinate.
+*   **clientY** (`number`): The client Y coordinate.
+*   **Returns**: `object` - An object with `x` and `y` properties representing the SVG coordinates.
+
+### `exportSVG()`
+
+Exports the canvas content as an SVG string. UI elements like selection boxes and focus frames are excluded from the export.
+
+*   **Returns**: `string` - The SVG content of the canvas.
+
+### `exportImage([format], [quality])`
+
+Exports the canvas content as an image (PNG, JPEG, or WebP).
+
+*   **[format]** (`string`, optional): The image format (`'png'`, `'jpeg'`, `'webp'`). Defaults to `'png'`.
+*   **[quality]** (`number`, optional): The image quality (0-1) for JPEG/WebP. Defaults to `1`.
+*   **Returns**: `Promise<Blob>` - A promise that resolves with the image data as a `Blob`.
+
+### `resize(width, height)`
+
+Resizes the canvas to the specified dimensions.
+
+*   **width** (`number`): The new width of the canvas.
+*   **height** (`number`): The new height of the canvas.
+
+### `toggleGrid()`
+
+Toggles the visibility of the background grid.
+
+### `on(event, callback)`
+
+Registers an event listener for a custom canvas event.
+
+*   **event** (`string`): The name of the event to listen for.
+*   **callback** (`Function`): The callback function to execute when the event is emitted.
+
+### `off(event, callback)`
+
+Removes an event listener.
+
+*   **event** (`string`): The name of the event.
+*   **callback** (`Function`): The callback function to remove.
+
+### `emit(event, [data])`
+
+Emits a custom canvas event.
+
+*   **event** (`string`): The name of the event to emit.
+*   **[data]** (`object`, optional): Optional data to pass with the event.
+
+### `getInfo()`
+
+Gets information about the current state of the canvas.
+
+*   **Returns**: `object` - An object containing canvas dimensions, stroke counts, active tool, and other status information.
+
+### `destroy()`
+
+Destroys the canvas instance, removes all DOM elements, and cleans up event listeners and managers.
+
+## Events
+
+The `omdCanvas` emits the following custom events:
+
+*   `strokeAdded`: Fired when a new stroke is added to the canvas.
+*   `strokeRemoved`: Fired when a stroke is removed from the canvas.
+*   `cleared`: Fired when all strokes are cleared from the canvas.
+*   `selectionChanged`: Fired when the selection of strokes changes.
+*   `resized`: Fired when the canvas is resized.
+*   `pointerDown`, `pointerMove`, `pointerUp`, `pointerCancel`, `pointerEnter`, `pointerLeave`: Pointer events, normalized to canvas coordinates.
+*   `keyDown`, `keyUp`: Keyboard events.
+*   `wheel`: Wheel events.
+*   `focusFrameCreated`, `focusFrameRemoved`, `focusFrameActivated`, `focusFramesCleared`: Events related to focus frame management.
+*   `destroyed`: Fired when the canvas instance is destroyed.

package/docs/api/omdConfigManager.md

@@ -0,0 +1,192 @@
+# omdConfigManager
+
+A module for managing the configuration of the OMD library. It handles loading settings from a JSON file, providing default values, and allowing runtime modifications.
+
+## Overview
+
+The configuration is managed as a single JSON object. The system can be initialized with a path to a `omdConfig.json` file, or it will fall back to a default configuration. The manager supports both asynchronous and synchronous access to configuration values.
+
+### Default Configuration
+
+If no `omdConfig.json` is found, the following default structure is used:
+
+```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
+        }
+    }
+}
+```
+
+## Core Functions
+
+
+```javascript
+import {
+  initializeConfig,
+  getConfig,
+  getConfigSync,
+  setConfig,
+  getConfigValue,
+  setConfigValue,
+  getDefaultConfig,
+  isEnabled,
+  useImplicitMultiplication,
+  getMultiplicationSymbol,
+  updateConfig,
+  resetConfig,
+  reloadConfig,
+  getConfigAsync,
+  getDotRadius,
+  getFontWeight
+} from 'omd-library';
+```
+
+
+#### `initializeConfig(configSource)`
+Loads the configuration. This should be called once when your application starts.
+- **Parameters:**
+  - `configSource` {string | Object} (optional) - A path to a JSON configuration file or a configuration object to use directly.
+- **Returns:** `Promise<void>`
+
+```javascript
+// Load from default path ('./omd/config/omdConfig.json')
+await initializeConfig();
+
+// Or load from a specific path
+await initializeConfig('./my-custom-config.json');
+
+// Or provide a config object directly
+await initializeConfig({ multiplication: { symbol: '*' } });
+```
+
+---
+
+
+#### `getConfig()`
+Asynchronously gets the entire configuration object. Loads it with defaults if it hasn't been loaded yet.
+- **Returns:** `Promise<Object>` - A promise that resolves to the configuration object.
+
+---
+
+
+#### `getConfigSync()`
+Synchronously gets the entire configuration object. **Note:** If the configuration has not been loaded yet, this will return the default configuration.
+- **Returns:** `Object` - The configuration object.
+
+---
+
+
+#### `setConfig(config)`
+Sets the entire configuration, merging it with the default values.
+- **Parameters:**
+  - `config` {Object} - The configuration object to set.
+
+---
+
+
+#### `getConfigValue(path)`
+Gets a specific configuration value using a dot-separated path.
+- **Parameters:**
+  - `path` {string} - The path to the value (e.g., `'multiplication.symbol'`).
+- **Returns:** `any` - The value at the specified path.
+
+---
+
+
+#### `setConfigValue(path, value)`
+Sets a specific configuration value using a dot-separated path.
+- **Parameters:**
+  - `path` {string} - The path to the value.
+  - `value` {any} - The new value to set.
+
+
+## Utility Functions
+
+#### `getMultiplicationSymbol()`
+- **Returns:** `string` - The configured symbol for multiplication.
+
+#### `useImplicitMultiplication(combination)`
+- **Parameters:**
+  - `combination` {string} (optional) - The context of the multiplication (e.g., `'constantVariable'`).
+- **Returns:** `boolean` - Whether to use implicit multiplication in that context or globally if no combination is provided.
+
+#### `getDotRadius(level)`
+- **Parameters:**
+  - `level` {number} - The step level (0, 1, or 2).
+- **Returns:** `number` - The configured dot radius for that level in the step visualizer.
+
+#### `getFontWeight(level)`
+- **Parameters:**
+  - `level` {number} - The step level (0, 1, or 2).
+- **Returns:** `number` - The configured font weight for that level.
+#### `getDefaultConfig()`
+- **Returns:** `Object` - The default configuration object.
+
+#### `isEnabled(category, setting)`
+- **Parameters:**
+  - `category` {string} - The configuration category (e.g., 'multiplication').
+  - `setting` {string} - The specific setting to check.
+- **Returns:** `boolean` - Whether the setting is enabled.
+
+#### `updateConfig(category, setting, value)`
+- **Parameters:**
+  - `category` {string} - The configuration category.
+  - `setting` {string} - The setting to update.
+  - `value` {any} - The new value.
+
+#### `resetConfig()`
+- **Throws:** Always throws an error. (Direct file editing is required.)
+
+#### `reloadConfig()`
+- **Returns:** `Promise<Object>` - Promise that resolves to the reloaded configuration.
+
+#### `getConfigAsync()`
+- **Returns:** `Promise<Object>` - Promise that resolves to the configuration object.
+
+
+## Example Usage
+
+```javascript
+import { initializeConfig, getConfigValue, setConfigValue, getMultiplicationSymbol } from 'omd-library';
+
+// Initialize at the start of your application
+(async () => {
+    await initializeConfig();
+
+    // Get a specific value
+    const multSymbol = getConfigValue('multiplication.symbol');
+    console.log(`Multiplication symbol is: ${multSymbol}`); // Output: ·
+
+    // Or use a dedicated utility function
+    console.log(`Multiplication symbol is: ${getMultiplicationSymbol()}`); // Output: ·
+
+    // Change a value at runtime
+    setConfigValue('multiplication.symbol', '*');
+    console.log(`New multiplication symbol is: ${getMultiplicationSymbol()}`); // Output: *
+})();
+```