@teachinglab/omd 0.1.4 → 0.1.5

package/docs/api/omdUtilities.md

@@ -1,70 +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.
-
-## 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.
-
-- **Parameters:**
-  - `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`).
-- **Returns:** {class} The appropriate `omdNode` class constructor.
-
----
-
-#### `getNodeForAST(ast)`
-
-A wrapper function that takes a complete math.js AST node and returns the corresponding OMD node class. It uses `astToOmdType` internally.
-
-- **Parameters:**
-  - `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 used for precise layout calculations.
-
-- **Parameters:**
-  - `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 is based on the complexity of the numerator and denominator.
-
-- **Parameters:**
-  - `ast` {Object} - The AST node representing a division operation.
-- **Returns:** {boolean} `true` if it should be 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 is used by `shouldUseFractionNotation` to decide on rendering style.
-
-- **Parameters:**
-  - `ast` {Object} - The AST node to check.
-- **Returns:** {boolean} `true` if the expression is considered complex, `false` otherwise.
-
-### Example
-
-```javascript
-import { getNodeForAST, getTextBounds } from './omd/omdUtilities.js';
-
-// Example of getting a node class
-const ast = math.parse('x + 2');
-const NodeClass = getNodeForAST(ast);
-const node = new NodeClass(ast);
-
-// 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,148 +1,123 @@
-# omdVariableNode
-
-Represents a variable (like x, y, a, b) in mathematical expressions.
-
-## Class: `omdVariableNode extends omdLeafNode`
-
-```javascript
-import { omdVariableNode } from './omd/nodes/omdVariableNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdVariableNode(nodeData)
-```
-
-**Parameters:**
-- `nodeData` {Object|string} - The AST node data or variable name
-
-**Description:**
-Creates a node representing a variable. Usually created automatically when parsing expressions.
-
-### Properties
-
-Inherits all properties from [`omdLeafNode`](./omdLeafNode.md), plus:
-
-#### `name`
-- **Type:** string
-- **Description:** The variable name (e.g., 'x', 'y', 'theta')
-
-#### `type`
-- **Type:** string
-- **Description:** Always "variable"
-
-#### `textElement`
-- **Type:** SVGElement
-- **Description:** The SVG text element displaying the variable name
-
-### Methods
-
-Inherits all methods from [`omdLeafNode`](./omdLeafNode.md), plus:
-
-#### `parseName(nodeData)`
-Internal method to extract variable name from AST data.
-- **Returns:** string
-
----
-
-#### `parseType()`
-Internal method to set node type.
-- **Returns:** "variable"
-
----
-
-#### `computeDimensions()`
-Calculates dimensions with padding around the variable.
-Overrides base class method.
-
----
-
-#### `updateLayout()`
-Updates the layout of the node.
-Overrides base class method.
-
----
-
-#### `toMathJSNode()`
-Converts to math.js AST format.
-- **Returns:** Object - A math.js-compatible AST node with:
-  - `type`: "SymbolNode"
-  - `name`: The variable name
-  - `id`: Node ID
-  - `provenance`: Provenance array
-
----
-
-#### `highlight(color)`
-Highlights the node and sets text color to white.
-- `color` {omdColor} - The highlight color
-
----
-
-#### `clearProvenanceHighlights()`
-Clears highlights and resets text color.
-
----
-
-#### `toString()`
-Convert to string representation.
-- **Returns:** string - The variable name
-
----
-
-#### `evaluate(variables)`
-Evaluates the variable by looking up its value in a map.
-- `variables` {Object} - A map of variable names to their numeric values
-- **Returns:** number - The value of the variable
-- **Throws:** Error if variable is not defined in the map
-
----
-
-#### `simplify()`
-Attempt to simplify the variable.
-- **Returns:** Object
-  - `success`: false (variables cannot be simplified)
-  - `newRoot`: null
-  - `message`: "Cannot simplify a variable"
-
-### Static Methods
-
-#### `fromName(name)`
-Create a variable node from a name.
-- `name` {string} - The variable name
-- **Returns:** omdVariableNode
-
-### Examples
-
-#### Creating Variables
-
-```javascript
-// From a name
-const nodeX = omdVariableNode.fromName('x');
-const nodeTheta = omdVariableNode.fromName('θ');
-
-// From AST data
-const node = new omdVariableNode({
-  type: 'SymbolNode',
-  name: 'x'
-});
-
-// Direct string name
-const nodeY = new omdVariableNode('y');
-```
-
-#### Rendering Variables
-
-```javascript
-const node = omdVariableNode.fromName('x');
-node.setFontSize(24);
-node.computeDimensions(); // Calculate size with padding
-node.updateLayout(); // Position the text element
-```
-
-### 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/index.js

@@ -5,10 +5,10 @@
  * It exports all core OMD components and visualization tools from a single endpoint.
  * 
  * Usage:
- * import { omdTable, omdBalanceHanger, omdEquationNode, omdDisplay } from 'omd-library'
+ * import { omdTable, omdBalanceHanger, omdEquationNode, omdDisplay } from '@teachinglab/omd'
  * 
  * Or for dynamic imports:
- * const { omdTable } = await import('omd-library')
+ * const { omdTable } = await import('@teachinglab/omd')
  */
 
 // Export everything from the core OMD library (equations, nodes, display, etc.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teachinglab/omd",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "omd",
   "main": "./index.js",
   "module": "./index.js",