@teachinglab/omd 0.6.1 → 0.6.2

package/docs/api/omdUtilities.md

@@ -1,83 +1,83 @@
-# omdUtilities
-
-This module provides a collection of utility functions primarily used for mapping math.js AST nodes to OMD node classes, determining rendering behavior, and calculating text dimensions. These functions are internal helpers that support the core OMD node system.
-
-## Functions
-
-### `astToOmdType(type, ast)`
-
-Maps a math.js AST node type to its corresponding OMD node class. This function is crucial for dynamically creating the correct `omdNode` subclass based on the parsed expression.
-
--   **`type`** (`string`): The `type` property of the AST node (e.g., `"OperatorNode"`, `"ParenthesisNode"`).
--   **`ast`** (`object`): The full AST node object, which may contain additional context (e.g., `op` for `OperatorNode`, `fn` for `FunctionNode`).
--   **Returns**: `class` - The appropriate `omdNode` class constructor.
-
-**Detailed Logic:**
-
--   **`AssignmentNode`**: Returns `omdEquationNode`.
--   **`OperatorNode`**: 
-    -   If `op` is `'-'` and `args.length` is `1` (unary minus), returns `omdUnaryExpressionNode`.
-    -   If `op` is `'='`, returns `omdEquationNode`.
-    -   If `op` is `'^'`, returns `omdPowerNode`.
-    -   If `op` is `'/'`, returns `omdRationalNode`.
-    -   Otherwise (binary operator), returns `omdBinaryExpressionNode`.
--   **`ParenthesisNode`**: Returns `omdParenthesisNode`.
--   **`ConstantNode`**: Returns `omdConstantNode`.
--   **`SymbolNode`**: Returns `omdVariableNode`.
--   **`FunctionNode`**: 
-    -   If `fn.name` or `name` is `'multiply'` and `ast.implicit` is `true` (implicit multiplication), returns `omdBinaryExpressionNode`.
-    -   If `fn.name` or `name` is `'sqrt'`, returns `omdSqrtNode`.
-    -   Otherwise, returns `omdFunctionNode`.
--   **Default**: Returns `omdNode`.
-
-### `getNodeForAST(ast)`
-
-A wrapper function that takes a complete math.js AST node and returns the corresponding OMD node class. It uses `astToOmdType` internally, handling cases where the AST might have a `mathjs` property indicating its type.
-
--   **`ast`** (`object`): The math.js AST node.
--   **Returns**: `class` - The appropriate `omdNode` class constructor.
-
-### `getTextBounds(text, fontSize)`
-
-Calculates the rendered width and height of a given text string at a specific font size. This is achieved by creating a temporary, hidden `<span>` element in the DOM, applying the text and styling, measuring its dimensions, and then removing it.
-
--   **`text`** (`string`): The text content to measure.
--   **`fontSize`** (`number`): The font size in pixels.
--   **Returns**: `object` - An object with `width` and `height` properties.
-
-### `shouldUseFractionNotation(ast)`
-
-Determines whether a division operation (represented by an AST node) should be rendered as a fraction (stacked numerator over denominator) or as a linear division (e.g., `a / b`). This decision is based on the complexity of the numerator and denominator.
-
--   **`ast`** (`object`): The AST node representing a division operation.
--   **Returns**: `boolean` - `true` if the division should be rendered as a fraction, `false` otherwise.
-
-### `isComplexExpression(ast)`
-
-Checks if an AST node represents a "complex" expression, typically one that contains multiple operations or nested structures. This function is used by `shouldUseFractionNotation` to decide on the appropriate rendering style for fractions.
-
--   **`ast`** (`object`): The AST node to check.
--   **Returns**: `boolean` - `true` if the expression is considered complex, `false` otherwise.
-
-## Example
-
-```javascript
-import { getNodeForAST, getTextBounds } from '@teachinglab/omd'; // Assuming @teachinglab/omd exports these
-import * as math from 'mathjs';
-
-// Example of getting a node class for an expression
-const astExpression = math.parse('x + 2');
-const NodeClassExpression = getNodeForAST(astExpression);
-const nodeExpression = new NodeClassExpression(astExpression);
-console.log(nodeExpression.type); // e.g., "omdBinaryExpressionNode"
-
-// Example of getting a node class for an equation
-const astEquation = math.parse('y = 2x');
-const NodeClassEquation = getNodeForAST(astEquation);
-const nodeEquation = new NodeClassEquation(astEquation);
-console.log(nodeEquation.type); // "omdEquationNode"
-
-// Example of getting text bounds
-const bounds = getTextBounds('Hello World', 24);
-console.log(`Text width: ${bounds.width}, height: ${bounds.height}`);
+# omdUtilities
+
+This module provides a collection of utility functions primarily used for mapping math.js AST nodes to OMD node classes, determining rendering behavior, and calculating text dimensions. These functions are internal helpers that support the core OMD node system.
+
+## Functions
+
+### `astToOmdType(type, ast)`
+
+Maps a math.js AST node type to its corresponding OMD node class. This function is crucial for dynamically creating the correct `omdNode` subclass based on the parsed expression.
+
+-   **`type`** (`string`): The `type` property of the AST node (e.g., `"OperatorNode"`, `"ParenthesisNode"`).
+-   **`ast`** (`object`): The full AST node object, which may contain additional context (e.g., `op` for `OperatorNode`, `fn` for `FunctionNode`).
+-   **Returns**: `class` - The appropriate `omdNode` class constructor.
+
+**Detailed Logic:**
+
+-   **`AssignmentNode`**: Returns `omdEquationNode`.
+-   **`OperatorNode`**: 
+    -   If `op` is `'-'` and `args.length` is `1` (unary minus), returns `omdUnaryExpressionNode`.
+    -   If `op` is `'='`, returns `omdEquationNode`.
+    -   If `op` is `'^'`, returns `omdPowerNode`.
+    -   If `op` is `'/'`, returns `omdRationalNode`.
+    -   Otherwise (binary operator), returns `omdBinaryExpressionNode`.
+-   **`ParenthesisNode`**: Returns `omdParenthesisNode`.
+-   **`ConstantNode`**: Returns `omdConstantNode`.
+-   **`SymbolNode`**: Returns `omdVariableNode`.
+-   **`FunctionNode`**: 
+    -   If `fn.name` or `name` is `'multiply'` and `ast.implicit` is `true` (implicit multiplication), returns `omdBinaryExpressionNode`.
+    -   If `fn.name` or `name` is `'sqrt'`, returns `omdSqrtNode`.
+    -   Otherwise, returns `omdFunctionNode`.
+-   **Default**: Returns `omdNode`.
+
+### `getNodeForAST(ast)`
+
+A wrapper function that takes a complete math.js AST node and returns the corresponding OMD node class. It uses `astToOmdType` internally, handling cases where the AST might have a `mathjs` property indicating its type.
+
+-   **`ast`** (`object`): The math.js AST node.
+-   **Returns**: `class` - The appropriate `omdNode` class constructor.
+
+### `getTextBounds(text, fontSize)`
+
+Calculates the rendered width and height of a given text string at a specific font size. This is achieved by creating a temporary, hidden `<span>` element in the DOM, applying the text and styling, measuring its dimensions, and then removing it.
+
+-   **`text`** (`string`): The text content to measure.
+-   **`fontSize`** (`number`): The font size in pixels.
+-   **Returns**: `object` - An object with `width` and `height` properties.
+
+### `shouldUseFractionNotation(ast)`
+
+Determines whether a division operation (represented by an AST node) should be rendered as a fraction (stacked numerator over denominator) or as a linear division (e.g., `a / b`). This decision is based on the complexity of the numerator and denominator.
+
+-   **`ast`** (`object`): The AST node representing a division operation.
+-   **Returns**: `boolean` - `true` if the division should be rendered as a fraction, `false` otherwise.
+
+### `isComplexExpression(ast)`
+
+Checks if an AST node represents a "complex" expression, typically one that contains multiple operations or nested structures. This function is used by `shouldUseFractionNotation` to decide on the appropriate rendering style for fractions.
+
+-   **`ast`** (`object`): The AST node to check.
+-   **Returns**: `boolean` - `true` if the expression is considered complex, `false` otherwise.
+
+## Example
+
+```javascript
+import { getNodeForAST, getTextBounds } from '@teachinglab/omd'; // Assuming @teachinglab/omd exports these
+import * as math from 'mathjs';
+
+// Example of getting a node class for an expression
+const astExpression = math.parse('x + 2');
+const NodeClassExpression = getNodeForAST(astExpression);
+const nodeExpression = new NodeClassExpression(astExpression);
+console.log(nodeExpression.type); // e.g., "omdBinaryExpressionNode"
+
+// Example of getting a node class for an equation
+const astEquation = math.parse('y = 2x');
+const NodeClassEquation = getNodeForAST(astEquation);
+const nodeEquation = new NodeClassEquation(astEquation);
+console.log(nodeEquation.type); // "omdEquationNode"
+
+// Example of getting text bounds
+const bounds = getTextBounds('Hello World', 24);
+console.log(`Text width: ${bounds.width}, height: ${bounds.height}`);
 ```

package/docs/api/omdVariableNode.md

@@ -1,123 +1,123 @@
-# omdVariableNode
-
-Represents a variable (like `x`, `y`, `a`, `b`) in mathematical expressions. This node handles the visual representation of variables, their evaluation, and conversion to math.js AST.
-
-## Class Definition
-
-```javascript
-export class omdVariableNode extends omdLeafNode
-```
-
-## Constructor
-
-### `new omdVariableNode(nodeData)`
-
-Creates a new `omdVariableNode` instance.
-
--   **`nodeData`** (`object` | `string`): The AST node data (from math.js, typically a `SymbolNode` with a `name` property) or the variable name as a string (e.g., `"x"`). The constructor extracts the variable `name` and creates the `textElement` for display.
-
-## Static Methods
-
-### `fromName(name)`
-
-Creates a variable node directly from a given name string. This is a convenience method for creating simple variable nodes without needing to construct a full AST object.
-
--   **`name`** (`string`): The variable name (e.g., `"x"`, `"theta"`).
--   **Returns**: `omdVariableNode` - A new instance of `omdVariableNode`.
-
-## Public Properties
-
--   **`name`** (`string`): The name of the variable (e.g., `'x'`, `'y'`, `'theta'`).
--   **`type`** (`string`): Always `"omdVariableNode"`.
--   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that displays the variable name.
-
-## Public Methods
-
-### `computeDimensions()`
-
-Calculates the dimensions of the node based on its text content, adding a small amount of padding around the variable name 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 `omdVariableNode` to a math.js-compatible AST format. It creates a `SymbolNode` with the variable's `name`, `id`, and `provenance`.
-
--   **Returns**: `object` - A math.js-compatible AST node with `type: "SymbolNode"` and `name` set to the variable name. The returned object also includes `id`, `provenance`, and a `clone` method for compatibility.
-
-### `highlight(color)`
-
-Applies a highlight to the node's background and sets the variable'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 variable's text color to its default (black).
-
-### `toString()`
-
-Converts the variable node to its string representation, which is simply its `name`.
-
--   **Returns**: `string` - The variable name.
-
-### `evaluate(variables)`
-
-Evaluates the variable by looking up its value in the provided `variables` map. If the variable is not defined in the map, it throws an error.
-
--   **`variables`** (`object`): A map of variable names to their numeric values.
--   **Returns**: `number` - The value of the variable.
--   **Throws**: `Error` if the variable is not defined in the map.
-
-## Internal Methods
-
--   **`parseName(nodeData)`**: Extracts the variable name from the constructor's `nodeData`. It handles both string input and AST objects with a `name` property.
--   **`parseType()`**: Sets the node's type. Always returns `"variable"`.
-
-## Examples
-
-#### Creating Variables
-
-```javascript
-import { omdVariableNode } from '@teachinglab/omd';
-import * as math from 'mathjs';
-
-// From a name string
-const nodeX = omdVariableNode.fromName('x');
-const nodeTheta = omdVariableNode.fromName('θ');
-
-// From AST data (e.g., from math.js parse result)
-const astNode = math.parse('y');
-const nodeY = new omdVariableNode(astNode);
-
-// Direct string name (less common, but supported)
-const nodeZ = new omdVariableNode('z');
-```
-
-#### Rendering Variables
-
-```javascript
-import { omdVariableNode } from '@teachinglab/omd';
-// import { jsvgContainer } from '@teachinglab/jsvg'; // if rendering directly
-
-const node = omdVariableNode.fromName('x');
-node.setFontSize(24);
-node.initialize(); // Computes dimensions and layout
-
-// To render, typically add to a parent node or an omdDisplay
-// const svgContainer = new jsvgContainer();
-// svgContainer.addChild(node);
-// document.body.appendChild(svgContainer.svgObject);
-```
-
-## See Also
-
--   [`omdLeafNode`](./omdLeafNode.md) - Parent class.
--   [`omdNode`](./omdNode.md) - Base class.
--   [`omdConstantNode`](./omdConstantNode.md) - For numeric values.
+# omdVariableNode
+
+Represents a variable (like `x`, `y`, `a`, `b`) in mathematical expressions. This node handles the visual representation of variables, their evaluation, and conversion to math.js AST.
+
+## Class Definition
+
+```javascript
+export class omdVariableNode extends omdLeafNode
+```
+
+## Constructor
+
+### `new omdVariableNode(nodeData)`
+
+Creates a new `omdVariableNode` instance.
+
+-   **`nodeData`** (`object` | `string`): The AST node data (from math.js, typically a `SymbolNode` with a `name` property) or the variable name as a string (e.g., `"x"`). The constructor extracts the variable `name` and creates the `textElement` for display.
+
+## Static Methods
+
+### `fromName(name)`
+
+Creates a variable node directly from a given name string. This is a convenience method for creating simple variable nodes without needing to construct a full AST object.
+
+-   **`name`** (`string`): The variable name (e.g., `"x"`, `"theta"`).
+-   **Returns**: `omdVariableNode` - A new instance of `omdVariableNode`.
+
+## Public Properties
+
+-   **`name`** (`string`): The name of the variable (e.g., `'x'`, `'y'`, `'theta'`).
+-   **`type`** (`string`): Always `"omdVariableNode"`.
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that displays the variable name.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the node based on its text content, adding a small amount of padding around the variable name 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 `omdVariableNode` to a math.js-compatible AST format. It creates a `SymbolNode` with the variable's `name`, `id`, and `provenance`.
+
+-   **Returns**: `object` - A math.js-compatible AST node with `type: "SymbolNode"` and `name` set to the variable name. The returned object also includes `id`, `provenance`, and a `clone` method for compatibility.
+
+### `highlight(color)`
+
+Applies a highlight to the node's background and sets the variable'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 variable's text color to its default (black).
+
+### `toString()`
+
+Converts the variable node to its string representation, which is simply its `name`.
+
+-   **Returns**: `string` - The variable name.
+
+### `evaluate(variables)`
+
+Evaluates the variable by looking up its value in the provided `variables` map. If the variable is not defined in the map, it throws an error.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The value of the variable.
+-   **Throws**: `Error` if the variable is not defined in the map.
+
+## Internal Methods
+
+-   **`parseName(nodeData)`**: Extracts the variable name from the constructor's `nodeData`. It handles both string input and AST objects with a `name` property.
+-   **`parseType()`**: Sets the node's type. Always returns `"variable"`.
+
+## Examples
+
+#### Creating Variables
+
+```javascript
+import { omdVariableNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// From a name string
+const nodeX = omdVariableNode.fromName('x');
+const nodeTheta = omdVariableNode.fromName('θ');
+
+// From AST data (e.g., from math.js parse result)
+const astNode = math.parse('y');
+const nodeY = new omdVariableNode(astNode);
+
+// Direct string name (less common, but supported)
+const nodeZ = new omdVariableNode('z');
+```
+
+#### Rendering Variables
+
+```javascript
+import { omdVariableNode } from '@teachinglab/omd';
+// import { jsvgContainer } from '@teachinglab/jsvg'; // if rendering directly
+
+const node = omdVariableNode.fromName('x');
+node.setFontSize(24);
+node.initialize(); // Computes dimensions and layout
+
+// To render, typically add to a parent node or an omdDisplay
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(node);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - Parent class.
+-   [`omdNode`](./omdNode.md) - Base class.
+-   [`omdConstantNode`](./omdConstantNode.md) - For numeric values.

package/docs/api/selectTool.md

@@ -1,74 +1,74 @@
-
-# SelectTool
-
-The `SelectTool` is a tool for selecting, moving, and deleting stroke segments on the canvas. It extends the `Tool` class.
-
-## Class Definition
-
-```javascript
-export class SelectTool extends Tool {
-    // ...
-}
-```
-
-## Constructor
-
-### `new SelectTool(canvas, [options])`
-
-Creates a new `SelectTool` instance.
-
-*   **canvas** (`OMDCanvas`): The canvas instance.
-*   **[options]** (`object`, optional): Configuration options for the tool.
-    *   **selectionColor** (`string`, optional): The color of the selection box. Defaults to `'#007bff'`.
-    *   **selectionOpacity** (`number`, optional): The opacity of the selection box. Defaults to `0.3`.
-
-## Public Methods
-
-### `onPointerDown(event)`
-
-Handles the pointer down event to start a selection.
-
-*   **event** (`PointerEvent`): The pointer event.
-
-### `onPointerMove(event)`
-
-Handles the pointer move event to update the selection box.
-
-*   **event** (`PointerEvent`): The pointer event.
-
-### `onPointerUp(event)`
-
-Handles the pointer up event to complete the selection.
-
-*   **event** (`PointerEvent`): The pointer event.
-
-### `onCancel()`
-
-Cancels the current selection operation.
-
-### `onKeyboardShortcut(key, event)`
-
-Handles keyboard shortcuts for selection-related actions.
-
-*   **key** (`string`): The key that was pressed.
-*   **event** (`KeyboardEvent`): The keyboard event.
-*   **Returns**: `boolean` - True if the shortcut was handled, false otherwise.
-
-### `getCursor()`
-
-Gets the cursor for the tool.
-
-*   **Returns**: `string` - The CSS cursor name.
-
-### `clearSelection()`
-
-Clears the current selection.
-
-## Properties
-
-*   **displayName** (`string`): The display name of the tool.
-*   **description** (`string`): A description of the tool.
-*   **icon** (`string`): The icon for the tool.
-*   **shortcut** (`string`): The keyboard shortcut for the tool.
-*   **category** (`string`): The category of the tool.
-*   **selectedSegments** (`Map<string, Set<number>>`): A map of selected segments, where the key is the stroke ID and the value is a set of segment indices.
+
+# SelectTool
+
+The `SelectTool` is a tool for selecting, moving, and deleting stroke segments on the canvas. It extends the `Tool` class.
+
+## Class Definition
+
+```javascript
+export class SelectTool extends Tool {
+    // ...
+}
+```
+
+## Constructor
+
+### `new SelectTool(canvas, [options])`
+
+Creates a new `SelectTool` instance.
+
+*   **canvas** (`OMDCanvas`): The canvas instance.
+*   **[options]** (`object`, optional): Configuration options for the tool.
+    *   **selectionColor** (`string`, optional): The color of the selection box. Defaults to `'#007bff'`.
+    *   **selectionOpacity** (`number`, optional): The opacity of the selection box. Defaults to `0.3`.
+
+## Public Methods
+
+### `onPointerDown(event)`
+
+Handles the pointer down event to start a selection.
+
+*   **event** (`PointerEvent`): The pointer event.
+
+### `onPointerMove(event)`
+
+Handles the pointer move event to update the selection box.
+
+*   **event** (`PointerEvent`): The pointer event.
+
+### `onPointerUp(event)`
+
+Handles the pointer up event to complete the selection.
+
+*   **event** (`PointerEvent`): The pointer event.
+
+### `onCancel()`
+
+Cancels the current selection operation.
+
+### `onKeyboardShortcut(key, event)`
+
+Handles keyboard shortcuts for selection-related actions.
+
+*   **key** (`string`): The key that was pressed.
+*   **event** (`KeyboardEvent`): The keyboard event.
+*   **Returns**: `boolean` - True if the shortcut was handled, false otherwise.
+
+### `getCursor()`
+
+Gets the cursor for the tool.
+
+*   **Returns**: `string` - The CSS cursor name.
+
+### `clearSelection()`
+
+Clears the current selection.
+
+## Properties
+
+*   **displayName** (`string`): The display name of the tool.
+*   **description** (`string`): A description of the tool.
+*   **icon** (`string`): The icon for the tool.
+*   **shortcut** (`string`): The keyboard shortcut for the tool.
+*   **category** (`string`): The category of the tool.
+*   **selectedSegments** (`Map<string, Set<number>>`): A map of selected segments, where the key is the stroke ID and the value is a set of segment indices.