@teachinglab/omd 0.5.6 → 0.5.8

package/npm-docs/api/omdOperatorNode.md

@@ -0,0 +1,92 @@
+# omdOperatorNode
+
+Represents an operator symbol (e.g., `+`, `-`, `*`, `÷`) as a leaf node in the expression tree. This node handles the visual representation of operators, including mapping common operation names to their appropriate symbols and applying styling.
+
+## Class Definition
+
+```javascript
+export class omdOperatorNode extends omdLeafNode
+```
+
+## Constructor
+
+### `new omdOperatorNode(nodeData)`
+
+Creates a new `omdOperatorNode` instance.
+
+-   **`nodeData`** (`object` | `string`): The AST node data (from math.js) or the operator symbol as a string (e.g., `"+"`, `"*"`). The constructor maps common operation names (like `"multiply"`) to their display symbols (like `"×"`), respecting the configured multiplication symbol.
+
+## Public Properties
+
+-   **`opName`** (`string`): The internal name of the operator (e.g., `"*"`, `"+"`). This might differ from the displayed symbol for multiplication.
+-   **`type`** (`string`): Always `"omdOperatorNode"`.
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that displays the operator symbol.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the node based on its text content, adding a small amount of padding around the operator symbol to improve visual spacing.
+
+-   **Overrides**: `omdLeafNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the node. This method primarily calls the superclass's `updateLayout`.
+
+-   **Overrides**: `omdLeafNode.updateLayout()`.
+
+### `toMathJSNode()`
+
+Converts the `omdOperatorNode` to a math.js-compatible AST format. It creates a minimal `OperatorNode` AST object.
+
+-   **Returns**: `object` - A math.js-compatible AST node with `type: "OperatorNode"`, `op` (operator symbol), `fn` (function name, typically same as `op`), and an empty `args` array. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the operator node to its string representation, which is simply its `opName`.
+
+-   **Returns**: `string` - The operator symbol (e.g., `"+"`, `"*"`).
+
+### `highlight(color)`
+
+Applies a highlight to the node's background and sets the operator's text color to white for better contrast. This method respects the `isExplainHighlighted` lock.
+
+-   **`color`** (`string`): The color of the highlight.
+
+### `clearProvenanceHighlights()`
+
+Clears any provenance-related highlights from the node and resets the operator's text color to its default (black).
+
+## Internal Methods
+
+-   **`parseOpName(nodeData)`**: Extracts the operator's internal name from the constructor's `nodeData`. It handles mapping from math.js function names (e.g., `"multiply"`) to display symbols (e.g., `"×"`), using the configured multiplication symbol.
+-   **`parseType()`**: Sets the node's type. Always returns `"operator"`.
+
+## Example
+
+```javascript
+import { omdOperatorNode } from '@teachinglab/omd';
+
+// Create operator nodes from strings
+const plus = new omdOperatorNode('+');
+const times = new omdOperatorNode('*'); // Displays as × (configurable via omdConfigManager)
+
+// Create operator node from AST data (e.g., from math.js parse result)
+const minus = new omdOperatorNode({
+  type: 'OperatorNode',
+  op: '-',
+  fn: 'subtract'
+}); // Displays as −
+
+// To render, typically add to a parent node or an omdDisplay
+// node.setFontSize(24);
+// node.initialize(); // Computes dimensions and layout
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - The parent class for all leaf nodes.
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - A common consumer of operator nodes.
+-   [`omdUnaryExpressionNode`](./omdUnaryExpressionNode.md) - Another consumer of operator nodes (e.g., for unary minus).

package/npm-docs/api/omdParenthesisNode.md

@@ -0,0 +1,134 @@
+# omdParenthesisNode
+
+Represents a parenthetical grouping in a mathematical expression, such as `(x + 2)`. This node is crucial for enforcing the correct order of operations and visually grouping parts of an expression.
+
+## Class Definition
+
+```javascript
+export class omdParenthesisNode extends omdNode
+```
+
+## Constructor
+
+### `new omdParenthesisNode(astNodeData)`
+
+Creates a new `omdParenthesisNode` instance.
+
+-   **`astNodeData`** (`object`): The math.js AST node for the parenthesized expression. It must contain a `content` property (or `args[0]`) which is the AST for the inner expression.
+
+During construction, it creates `omdGroupNode` instances for the opening and closing parentheses and an `omdNode` for the inner expression.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdParenthesisNode` from a string representation of a parenthesized expression. The input string must start and end with parentheses.
+
+-   **`expressionString`** (`string`): The expression, which must be enclosed in parentheses (e.g., `"(2 * x)"`).
+-   **Returns**: `omdParenthesisNode` - A new instance.
+-   **Throws**: `Error` if `math.js` is not available, if the string is not properly enclosed in parentheses, or if it's not a valid parenthesized expression.
+
+## Public Properties
+
+-   **`expression`** (`omdNode`): The node representing the mathematical expression inside the parentheses.
+-   **`open`** (`omdGroupNode`): The `omdGroupNode` for the opening parenthesis `(`. 
+-   **`closed`** (`omdGroupNode`): The `omdGroupNode` for the closing parenthesis `)`. 
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the parenthesis node. It sums the widths of the opening parenthesis, the inner expression, and the closing parenthesis. The height is determined by the maximum height of these components plus a small amount of padding that scales with font size.
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the parenthesis node and its children. It positions the inner `expression` and then centers the `open` and `closed` parentheses vertically around the mathematical baseline of the inner expression. This ensures proper visual alignment, especially for expressions containing superscripts or subscripts.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `getAlignmentBaseline()`
+
+Returns the vertical y-coordinate for alignment. For a parenthesis node, this is the baseline of its inner expression.
+
+-   **Overrides**: `omdNode.getAlignmentBaseline()`.
+
+### `clone()`
+
+Creates a deep, structural clone of the parenthesis node, including its inner `expression` and `omdGroupNode` children. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdParenthesisNode` - A new, identical instance of the parenthesis node.
+
+### `isConstant()`
+
+Checks if the inner expression is a constant value.
+
+-   **Returns**: `boolean` - `true` if `this.expression.isConstant()` is `true`, `false` otherwise.
+
+### `getValue()`
+
+Returns the numerical value of the inner expression, if it is constant.
+
+-   **Returns**: `number`.
+-   **Throws**: `Error` if the inner expression is not constant or cannot be evaluated.
+
+### `toMathJSNode()`
+
+Converts the `omdParenthesisNode` back into its math.js AST representation. It creates a `ParenthesisNode` AST object with the converted inner expression.
+
+-   **Returns**: `object` - A math.js `ParenthesisNode` AST object. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the node to its string representation, including the parentheses.
+
+-   **Returns**: `string` - e.g., `"(x + 2)"`.
+
+### `evaluate(variables)`
+
+Evaluates the inner expression of the parenthesis node.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The result of the inner expression's evaluation.
+-   **Throws**: `Error` if the inner expression cannot be evaluated.
+
+### `isNecessary()`
+
+Checks if the parentheses are mathematically necessary to maintain the correct order of operations, based on the parent node's context and the type of the inner expression. For example, parentheses around a simple constant or variable are generally not necessary, but they are often required around complex expressions within a power or binary operation.
+
+-   **Returns**: `boolean` - `true` if the parentheses are required, `false` otherwise.
+
+## Internal Methods
+
+-   **`createParenthesis(symbol)`**: Creates an `omdGroupNode` for an opening or closing parenthesis.
+-   **`createExpression(ast)`**: Creates an `omdNode` instance for the inner expression from its AST.
+
+## Example
+
+```javascript
+import { omdParenthesisNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create a node representing (x + 2)
+const innerExpressionAst = math.parse('x + 2');
+const parenNode = new omdParenthesisNode({ content: innerExpressionAst });
+
+// Set font size and render
+parenNode.setFontSize(28);
+parenNode.initialize();
+
+// The simplification engine might remove these parentheses if they are not necessary
+// const simplified = parenNode.simplify();
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(parenNode);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdGroupNode`](./omdGroupNode.md) - The class used to render the individual `(` and `)` symbols.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - A common type for the inner expression within parentheses.

package/npm-docs/api/omdPopup.md

@@ -0,0 +1,192 @@
+# omdPopup
+
+The `omdPopup` class handles the creation and management of interactive popups for node overlays. These popups can be used for text input or for drawing with a pen tool, often integrated with a transcription service for converting handwriting to text.
+
+## Class Definition
+
+```javascript
+export class omdPopup
+```
+
+## Constructor
+
+### `new omdPopup(targetNode, parentElement, [options])`
+
+Creates a new `omdPopup` instance.
+
+-   **`targetNode`** (`omdNode`): The OMD node to which the popup is logically attached. Its dimensions can influence the popup's size.
+-   **`parentElement`** (`jsvgElement`): The parent `jsvgElement` (or `jsvgGroup`) to which the popup's SVG elements will be added.
+-   **`options`** (`object`, optional): Configuration options for the popup:
+    -   `editable` (`boolean`): Whether the popup's input area is editable. Default: `true`.
+    -   `animationDuration` (`number`): The duration of the show/hide animation in milliseconds. Default: `200`.
+
+## Public Properties
+
+-   **`popup`** (`jsvgLayoutGroup`): The main SVG group element that contains all popup components.
+-   **`popupBackground`** (`jsvgRect`): The background rectangle of the popup.
+-   **`popupTextInput`** (`jsvgTextInput`): The text input field element (active in `'text'` mode).
+-   **`penCanvas`** (`omdCanvas`): The drawing canvas instance (active in `'pen'` mode).
+-   **`penCanvasCleanup`** (`function`): A cleanup function for the `penCanvas`.
+-   **`currentMode`** (`string`): The current mode of the popup (`'text'` or `'pen'`).
+-   **`popupAnimationId`** (`number`): The ID of the current animation frame request.
+-   **`penButton`** (`jsvgButton`): The button to switch to `'pen'` mode.
+-   **`textButton`** (`jsvgButton`): The button to switch to `'text'` mode.
+-   **`clearButton`** (`jsvgButton`): The button to clear the current input.
+-   **`submitButton`** (`jsvgButton`): The button to submit the input.
+-   **`onValidateCallback`** (`function`): The callback function to execute when the user submits input.
+-   **`onClearCallback`** (`function`): The callback function to execute when the user clears input.
+-   **`popupWidth`** (`number`): The fixed width of the popup.
+-   **`buttonSize`** (`number`): The size (width and height) of the control buttons.
+-   **`margin`** (`number`): General margin/padding value used for layout.
+-   **`buttonSpacing`** (`number`): Spacing between buttons.
+-   **`canvasMinWidth`** (`number`): Minimum width for the pen canvas.
+-   **`canvasMinHeight`** (`number`): Minimum height for the pen canvas.
+-   **`popupHeightMultiplier`** (`number`): Multiplier for the target node's height to determine popup height.
+-   **`targetNodeDefaultHeight`** (`number`): Default height for the target node if not available.
+-   **`canvasTopOffset`** (`number`): Vertical offset for the pen canvas within the popup.
+-   **`canvasLeftOffset`** (`number`): Horizontal offset for the pen canvas within the popup.
+-   **`transcribedText`** (`string` | `null`): Stores the text result from pen-to-text transcription.
+
+## Public Methods
+
+### `show(x, y)`
+
+Creates and displays the popup at the specified coordinates with an animation.
+
+-   **`x`** (`number`): The x-coordinate for the popup's top-left corner.
+-   **`y`** (`number`): The y-coordinate for the popup's top-left corner.
+-   **Returns**: `Promise` - A promise that resolves when the show animation is complete.
+
+### `hide()`
+
+Hides the popup with an animation and performs cleanup.
+
+-   **Returns**: `Promise` - A promise that resolves when the hide animation is complete.
+
+### `toggle(x, y)`
+
+Toggles the visibility of the popup. If visible, it hides; otherwise, it shows.
+
+-   **`x`** (`number`): The x-coordinate for showing the popup.
+-   **`y`** (`number`): The y-coordinate for showing the popup.
+-   **Returns**: `Promise` - A promise that resolves when the animation is complete.
+
+### `setValidationCallback(callback)`
+
+Sets the callback function to be invoked when the user submits their input (e.g., by clicking the submit button).
+
+-   **`callback`** (`Function`): The function to call for validation.
+
+### `setClearCallback(callback)`
+
+Sets the callback function to be invoked when the user clears the input (e.g., by clicking the clear button).
+
+-   **`callback`** (`Function`): The function to call when clearing.
+
+### `getValue()`
+
+Retrieves the current input value from the popup. If in pen mode, it returns the last transcribed text and then clears it.
+
+-   **Returns**: `string` - The current input value.
+
+### `setValue(value)`
+
+Sets the input value of the popup's text field.
+
+-   **`value`** (`string`): The value to set.
+
+### `switchToMode(mode)`
+
+Switches the popup between `'text'` and `'pen'` input modes. This updates the visible input area and button states.
+
+-   **`mode`** (`string`): The mode to switch to. Can be `'text'` or `'pen'`.
+
+### `flashValidation(isValid)`
+
+Flashes the popup background (and associated elements) to visually indicate whether the user's input was valid or invalid.
+
+-   **`isValid`** (`boolean`): `true` for a success flash (greenish), `false` for an error flash (reddish).
+
+### `areExpressionsEquivalent(expr1, expr2)`
+
+Compares two mathematical expressions for equivalence. It uses `math.js` to simplify and evaluate expressions with random variable assignments to robustly check for mathematical equality.
+
+-   **`expr1`** (`string`): The first expression string.
+-   **`expr2`** (`string`): The second expression string.
+-   **Returns**: `boolean` - `true` if the expressions are mathematically equivalent, `false` otherwise.
+
+### `destroy()`
+
+Completely destroys the popup, removing all associated DOM elements, event listeners, and internal references. This method calls `hide()` internally to ensure a clean animated exit.
+
+### `repositionCanvasRelativeToPopup()`
+
+Manually triggers an update to the pen canvas's position to ensure it remains correctly aligned with the popup, especially after layout changes.
+
+## Internal Methods
+
+-   **`_createPopup()`**: Creates the main `jsvgLayoutGroup` for the popup, its background, and initializes buttons and input areas.
+-   **`_createButtons(popupWidth, popupHeight, buttonSize, margin, buttonSpacing)`**: Creates and positions the clear, submit, pen, and text mode switch buttons.
+-   **`_createTextInput(popupWidth, popupHeight, margin)`**: Creates and styles the `jsvgTextInput` element for text input mode.
+-   **`_createPenCanvas()`**: Initializes the `omdCanvas` instance for drawing in pen mode. It handles embedding the HTML canvas within an SVG `foreignObject` if necessary.
+-   **`_showPenMode()`**: Activates the pen drawing mode, hiding the text input and showing/creating the pen canvas.
+-   **`_showTextMode()`**: Activates the text input mode, hiding the pen canvas and showing the text input.
+-   **`_addCanvasToParent(element)`**: Adds the pen canvas's DOM element (or its `foreignObject` wrapper) to the appropriate parent, handling positioning.
+-   **`_updateButtonStates()`**: Updates the visual appearance of the mode switch buttons to reflect the `currentMode`.
+-   **`_positionPopup(x, y)`**: Sets the absolute position of the main popup SVG group.
+-   **`_animateOpacity(fromOpacity, toOpacity, duration)`**: Handles the smooth opacity animation for showing and hiding the popup.
+-   **`_flashAllElements(flashColor)`**: Applies a temporary background color flash to all relevant popup elements (background, canvas) to indicate validation feedback.
+-   **`_downloadCanvasAsBitmap()`**: Converts the content of the pen canvas to a PNG bitmap and initiates the transcription process.
+-   **`_transcribeCanvas(imageBlob)`**: Sends the pen canvas image data to the `omdTranscriptionService` for handwriting recognition.
+-   **`_setSubmitButtonLoading(isLoading)`**: Controls the loading state of the submit button, including a blinking animation.
+-   **`_startBlinkingAnimation()`**: Initiates the blinking animation for the submit button.
+-   **`_stopBlinkingAnimation()`**: Stops the blinking animation for the submit button.
+-   **`_setupResizeObserver()`**: Sets up a `ResizeObserver` to monitor changes in the popup's dimensions and reposition the pen canvas accordingly.
+-   **`_updateCanvasPosition()`**: Recalculates and applies the correct position and size for the pen canvas within the popup's content area.
+-   **`_cleanup()`**: Performs comprehensive cleanup of all popup-related DOM elements, event listeners, and internal references.
+
+## Modes
+
+The `omdPopup` has two primary interaction modes:
+
+-   **Text Mode**: This is the default mode, providing a standard text input field (`jsvgTextInput`).
+-   **Pen Mode**: This mode allows the user to draw directly inside the popup using an embedded `omdCanvas`. The drawing can then be transcribed to text using an external OCR service (via `omdTranscriptionService`).
+
+Users can switch between modes using the `'T'` (Text) and `'P'` (Pen) buttons on the popup.
+
+## Example Usage
+
+```javascript
+import { omdPopup } from '@teachinglab/omd';
+import { omdNode } from '@teachinglab/omd'; // Assuming you have an omdNode instance
+import { jsvgGroup } from '@teachinglab/jsvg'; // Assuming a parent jsvgElement
+
+// Create a dummy node and parent element for demonstration
+const targetNode = new omdNode({});
+const parentElement = new jsvgGroup();
+
+// Create a popup for a node
+const popup = new omdPopup(targetNode, parentElement);
+
+// Set a validation callback
+popup.setValidationCallback(() => {
+    const value = popup.getValue();
+    if (popup.areExpressionsEquivalent(value, 'correct')) {
+        popup.flashValidation(true);
+        popup.hide();
+    } else {
+        popup.flashValidation(false);
+    }
+});
+
+// Set a clear callback
+popup.setClearCallback(() => {
+    console.log('Popup input cleared!');
+});
+
+// Show the popup at a specific position
+// popup.show(100, 100);
+
+// To add the parentElement to the DOM for actual display:
+// document.body.appendChild(parentElement.svgObject);
+```

package/npm-docs/api/omdPowerNode.md

@@ -0,0 +1,132 @@
+# omdPowerNode
+
+Represents an exponentiation in a mathematical expression, such as `x^2` or `(a+b)^c`. This node handles the specific layout requirements of a base and a superscripted exponent, ensuring correct visual hierarchy and alignment.
+
+## Class Definition
+
+```javascript
+export class omdPowerNode extends omdNode
+```
+
+## Constructor
+
+### `new omdPowerNode(ast)`
+
+Creates a new `omdPowerNode` instance.
+
+-   **`ast`** (`object`): The math.js AST for the power operation. It must be an `OperatorNode` with `op: '^'` and an `args` array containing exactly two elements: the base and the exponent. Throws an error if the AST is invalid.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdPowerNode` from a string representation of a power expression. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The power expression as a string (e.g., `"x^2"`, `"(a+b)^c"`).
+-   **Returns**: `omdPowerNode` - A new instance.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid power expression.
+
+## Public Properties
+
+-   **`base`** (`omdNode`): The node representing the base of the power operation.
+-   **`exponent`** (`omdNode`): The node representing the exponent.
+-   **`value`** (`string`): The operator symbol for power, which is `"^"`.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the power node. It computes the dimensions of the base and exponent (scaling the exponent's font size down). The total width is the sum of their widths, and the total height accounts for the base's height plus the vertical offset needed for the superscripted exponent.
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the power node. It positions the `base` at the bottom of the node's bounding box to ensure space for the exponent above it. The `exponent` is then positioned to the right of the base and shifted upwards by a calculated superscript offset.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `getSuperscriptOffset()`
+
+Calculates the vertical offset (in pixels) by which the exponent should be raised above the base. This offset is a proportion of the current font size to ensure consistent scaling.
+
+-   **Returns**: `number` - The vertical offset.
+
+### `getAlignmentBaseline()`
+
+Calculates the vertical alignment point for the node. For a power node, the baseline is determined by the baseline of its `base` expression, ensuring proper alignment with other mathematical elements.
+
+-   **Overrides**: `omdNode.getAlignmentBaseline()`.
+
+### `clone()`
+
+Creates a deep, structural clone of the power node, including its `base` and `exponent` nodes. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdPowerNode` - A new, identical instance of the power node.
+
+### `toMathJSNode()`
+
+Converts the `omdPowerNode` back into its math.js AST representation. It creates an `OperatorNode` with `op: '^'` and `fn: 'pow'`, containing the converted base and exponent ASTs.
+
+-   **Returns**: `object` - A math.js `OperatorNode` for the power operation. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the node to its string representation, adding parentheses where necessary to preserve the correct order of operations for both the base and the exponent.
+
+-   **Returns**: `string` - e.g., `"(x+1)^2"`.
+
+### `evaluate(variables)`
+
+Evaluates the power expression by raising the evaluated base to the power of the evaluated exponent. It handles cases where base or exponent might not be numerical.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The result of the exponentiation, or `NaN` if base or exponent cannot be evaluated to a number.
+
+### `isSquare()`
+
+Checks if the exponent of the power node is the constant value `2`.
+
+-   **Returns**: `boolean`.
+
+### `isCube()`
+
+Checks if the exponent of the power node is the constant value `3`.
+
+-   **Returns**: `boolean`.
+
+## Internal Methods
+
+-   **`parseValue()`**: Sets the `value` property to `"^"`.
+-   **`createOperand(ast)`**: Creates an `omdNode` instance for the base or exponent from its AST.
+
+## Example
+
+```javascript
+import { omdPowerNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create a node representing x^2
+const ast = math.parse('x^2');
+const powerNode = new omdPowerNode(ast);
+
+// Set font size and render
+powerNode.setFontSize(32);
+powerNode.initialize();
+
+// Check properties
+console.log(powerNode.isSquare()); // true
+
+// Evaluate
+console.log(powerNode.evaluate({ x: 5 })); // 25
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(powerNode);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Can be used for complex bases or exponents.