@teachinglab/omd 0.1.3 → 0.1.5

package/docs/api/omdBinaryExpressionNode.md

@@ -1,227 +1,86 @@
-# 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
+# omdBinaryExpressionNode
+
+Represents a binary operation in a mathematical expression, such as addition (`a + b`), subtraction, multiplication, or division. This node is a cornerstone of the expression tree, containing a left operand, a right operand, and an operator.
+
+## Class Definition
+
+```javascript
+export class omdBinaryExpressionNode extends omdNode
+```
+
+## Constructor
+
+### `new omdBinaryExpressionNode(ast)`
+
+Creates a new `omdBinaryExpressionNode` instance.
+
+-   **`ast`** (`object`): The abstract syntax tree (AST) node from a parser like math.js. It must contain:
+    -   `args`: An array with at least two operand nodes.
+    -   `op`: The operator symbol (e.g., `+`, `*`).
+    -   `fn`: The function name for the operation (e.g., `add`, `multiply`).
+    -   `implicit` (`boolean`, optional): `true` if the multiplication is implicit (e.g., `2x`).
+
+During construction, the node automatically handles a critical piece of mathematical convention: **implicit multiplication**. Based on the configuration in `omdConfigManager`, it will:
+
+1.  **Reorder Operands**: If it encounters an expression like `x * 2`, it will automatically reorder it to the conventional `2 * x` by swapping the left and right child nodes.
+2.  **Determine Implicit Form**: It checks if the combination of operands (e.g., a constant and a variable) should be represented implicitly. If so, it removes the visible operator (`*`) and marks the node as implicit.
+
+## Public Properties
+
+-   **`left`** ([`omdNode`](./omdNode.md)): The node representing the left-hand side of the operation.
+-   **`right`** ([`omdNode`](./omdNode.md)): The node representing the right-hand side of the operation.
+-   **`op`** ([`omdOperatorNode`](./omdOperatorNode.md) | `null`): The node for the operator. This is `null` for implicit multiplication.
+-   **`operation`** (`string`): The name of the mathematical function (e.g., `'add'`, `'multiply'`).
+-   **`isImplicit`** (`boolean`): `true` if the node represents implicit multiplication.
+
+## Public Methods
+
+### `clone()`
+
+Creates a deep, recursive clone of the node, including its children (`left`, `right`, `op`). The new node's `provenance` property will link back to the ID of this original node.
+
+-   **Returns**: A new `omdBinaryExpressionNode` instance.
+
+### `evaluate(variables)`
+
+Recursively evaluates the expression and returns the numerical result.
+
+-   **`variables`** (`object`, optional): A map of variable names to their numeric values (e.g., `{ x: 5 }`).
+-   **Returns**: `number` - The result of the calculation.
+-   **Throws**: An `Error` for unsupported operations or division by zero.
+
+### `needsParentheses()`
+
+Determines if this expression needs to be wrapped in parentheses to maintain the correct order of operations when it is a child of another binary expression.
+
+-   **Returns**: `boolean` - `true` if parentheses are required.
+
+### `setHighlight(highlightOn, color)`
+
+Applies or removes a highlight from the node and all of its children (left, right, and operator).
+
+-   **`highlightOn`** (`boolean`): `true` to highlight, `false` to remove.
+-   **`color`** (`string`, optional): The color of the highlight.
+
+### `clearProvenanceHighlights()`
+
+Recursively clears all provenance-related highlights from this node and its children.
+
+### `toMathJSNode()`
+
+Converts the node back into a math.js-compatible AST format.
+
+-   **Returns**: `object` - A math.js OperatorNode.
+
+### `toString()`
+
+Converts the node into a human-readable string, automatically handling parentheses for precedence.
+
+-   **Returns**: `string` - The string representation of the expression.
+
+## Internal Methods
+
+-   **`_shouldUseImplicitMultiplication(left, right)`**: Checks the configuration to decide if implicit multiplication is appropriate for the given operand types.
+-   **`_shouldReorderMultiplication(left, right)`**: Determines if operands should be swapped to follow convention (e.g., `variable * constant` -> `constant * variable`).
+-   **`computeDimensions()`**: Calculates the bounding box of the expression.
+-   **`updateLayout()`**: Positions the left operand, operator, and right operand correctly, aligning them along their baseline.

package/docs/api/omdCanvas.md

@@ -1,142 +1,84 @@
-# 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.
+# omdCanvas
+
+The `omdCanvas` class is the core component for creating and managing an interactive 2D drawing surface. It provides the primary API for all canvas operations, including drawing and managing strokes, handling user input, and orchestrating various features like tools, a toolbar, and focus frames.
+
+## Class Definition
+
+```javascript
+export class omdCanvas
+```
+
+## Constructor
+
+### `new omdCanvas(container, [options])`
+
+Creates a new `omdCanvas` instance within a specified container element.
+
+-   **`container`** (`HTMLElement` | `string`): The HTML element or a CSS selector string for the container where the canvas will be rendered. Throws an error if the container is not found.
+-   **`options`** (`object`, optional): Configuration options for the canvas. These are passed to the `CanvasConfig` class. See the [Configuration Options](./configuration-options.md) for details.
+
+## Properties
+
+-   **`container`** (`HTMLElement`): The HTML container element for the canvas.
+-   **`config`** (`CanvasConfig`): The configuration object for the canvas.
+-   **`svg`** (`SVGElement`): The main `<svg>` element that serves as the drawing surface.
+-   **`backgroundLayer`** (`SVGGElement`): An SVG group (`<g>`) for background elements like the grid.
+-   **`drawingLayer`** (`SVGGElement`): The SVG group where all drawing strokes are rendered.
+-   **`uiLayer`** (`SVGGElement`): The SVG group for UI elements that overlay the drawing, such as selection boxes.
+-   **`focusFrameLayer`** (`SVGGElement`): The SVG group dedicated to holding `FocusFrame` elements.
+-   **`strokes`** (`Map<string, Stroke>`): A map of all stroke objects on the canvas, with their unique IDs as keys.
+-   **`selectedStrokes`** (`Set<string>`): A set of the IDs of all currently selected strokes.
+-   **`toolManager`** (`ToolManager`): The instance managing the active drawing tools (Pencil, Eraser, etc.).
+-   **`eventManager`** (`EventManager`): The instance managing all user input events.
+-   **`cursor`** (`Cursor`): The instance that manages the custom cursor's appearance and behavior.
+-   **`toolbar`** (`Toolbar`): The UI toolbar for tool selection (if enabled in config).
+-   **`focusFrameManager`** (`FocusFrameManager`): The instance managing focus frames (if enabled in config).
+
+## Public Methods
+
+### Stroke Management
+
+-   **`addStroke(stroke)`**: Adds a `Stroke` object to the canvas and renders it. Emits `strokeAdded`.
+-   **`removeStroke(strokeId)`**: Removes a stroke from the canvas by its ID. Emits `strokeRemoved`.
+-   **`clear()`**: Removes all strokes from the canvas. Emits `cleared`.
+
+### Selection
+
+-   **`selectStrokes(strokeIds)`**: Programmatically selects a set of strokes by their IDs. Emits `selectionChanged`.
+
+### Coordinate Conversion
+
+-   **`clientToSVG(clientX, clientY)`**: Converts screen coordinates (e.g., from a mouse event) to the canvas's local SVG coordinate system.
+    -   **Returns**: `{ x, y }` object.
+
+### Exporting
+
+-   **`exportSVG()`**: Exports the canvas drawing as a clean SVG string. UI layers (`uiLayer`, `focusFrameLayer`) are excluded.
+-   **`async exportImage([format], [quality])`**: Exports the canvas as a bitmap image.
+    -   **`format`** (`string`): `'png'`, `'jpeg'`, or `'webp'`. Default: `'png'`.
+    -   **`quality`** (`number`): For JPEG/WebP, a value from 0 to 1. Default: `1`.
+    -   **Returns**: `Promise<Blob>` that resolves with the image data.
+
+### Canvas Management
+
+-   **`resize(width, height)`**: Resizes the canvas. Emits `resized`.
+-   **`toggleGrid()`**: Toggles the visibility of the background grid.
+-   **`getInfo()`**: Returns an object with status information (dimensions, stroke count, active tool, etc.).
+-   **`destroy()`**: Completely removes the canvas and all associated managers, event listeners, and DOM elements. Emits `destroyed`.
+
+### Event Handling (Pub/Sub)
+
+-   **`on(event, callback)`**: Registers a listener for a custom canvas event.
+-   **`off(event, callback)`**: Removes a previously registered event listener.
+-   **`emit(event, [data])`**: Dispatches a custom event to all registered listeners.
+
+## Emitted Events
+
+The `omdCanvas` is an event emitter. You can listen for these events using the `on()` method.
+
+-   `strokeAdded`, `strokeRemoved`, `cleared`: Fired for stroke operations.
+-   `selectionChanged`: Fired when the set of selected strokes changes.
+-   `resized`: Fired when the canvas dimensions change.
+-   `pointerDown`, `pointerMove`, `pointerUp`, etc.: Raw input events, normalized by the `EventManager`.
+-   `focusFrameCreated`, `focusFrameRemoved`, etc.: Events from the `FocusFrameManager`.
+-   `destroyed`: Fired when the `destroy()` method has completed.