@teachinglab/omd 0.2.10 → 0.3.1

package/docs/api/omdParenthesisNode.md

@@ -1,134 +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.
+# 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/docs/api/omdPopup.md

@@ -1,192 +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);
+# 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);
 ```