@teachinglab/omd 0.1.4 → 0.1.6

package/canvas/tools/EraserTool.js

@@ -319,4 +319,4 @@ export class EraserTool extends Tool {
             }
         }
     }
-}
+}

package/canvas/tools/PencilTool.js

@@ -316,4 +316,4 @@ export class PencilTool extends Tool {
     getHelpText() {
         return `${super.getHelpText()}\nShortcuts: [ ] to adjust brush size`;
     }
-} 
+} 

package/canvas/tools/SelectTool.js

@@ -454,4 +454,4 @@ export class SelectTool extends Tool {
         newStroke.finish();
         this.canvas.addStroke(newStroke);
     }
-}
+}

package/docs/api/configuration-options.md

@@ -1,104 +1,198 @@
-# Configuration Options
-
-This document details all available configuration options for the OMD library, managed by the `omdConfigManager` module. These options allow you to customize various aspects of the library's behavior, appearance, and mathematical preferences.
-
-## Overview
-
-The OMD configuration is a single JavaScript object that can be loaded from a JSON file or set programmatically. It is organized into logical categories.
-
-## Default Configuration Structure
-
-If no custom configuration is provided, the library uses the following default structure:
-
-```json
-{
-    "multiplication": {
-        "symbol": "·",
-        "forceImplicit": false,
-        "implicitCombinations": {
-            "constantVariable": true,
-            "variableConstant": false,
-            "parenthesisAfterVariable": true,
-            "parenthesisAfterConstant": true,
-            "variableParenthesis": true,
-            "parenthesisParenthesis": true,
-            "parenthesisVariable": true,
-            "parenthesisConstant": true,
-            "variableVariable": true
-        }
-    },
-    "stepVisualizer": {
-        "dotSizes": {
-            "level0": 8,
-            "level1": 6,
-            "level2": 4
-        },
-        "fontWeights": {
-            "level0": 400,
-            "level1": 300,
-            "level2": 200
-        }
-    }
-}
-```
-
-## Configuration Categories and Options
-
-### `multiplication`
-
-Settings related to how multiplication is displayed and handled.
-
--   **`symbol`** {string}
-    -   The character used to represent multiplication. Default: `"·"` (middle dot).
-    -   Example: `"*"` or `"×"`.
-
--   **`forceImplicit`** {boolean}
-    -   If `true`, implicit multiplication (e.g., `2x` instead of `2 * x`) is always used where mathematically valid, overriding `implicitCombinations`.
-    -   Default: `false`.
-
--   **`implicitCombinations`** {Object}
-    -   An object defining specific scenarios where implicit multiplication should be used. Each property is a boolean.
-    -   **`constantVariable`** {boolean}: `2x` (Default: `true`)
-    -   **`variableConstant`** {boolean}: `x2` (Default: `false`)
-    -   **`parenthesisAfterVariable`** {boolean}: `x(y+z)` (Default: `true`)
-    -   **`parenthesisAfterConstant`** {boolean}: `2(x+y)` (Default: `true`)
-    -   **`variableParenthesis`** {boolean}: `(x+y)z` (Default: `true`)
-    -   **`parenthesisParenthesis`** {boolean}: `(x+y)(a+b)` (Default: `true`)
-    -   **`parenthesisVariable`** {boolean}: `(x+y)z` (Default: `true`)
-    -   **`parenthesisConstant`** {boolean}: `(x+y)2` (Default: `true`)
-    -   **`variableVariable`** {boolean}: `xy` (Default: `true`)
-
-### `stepVisualizer`
-
-Settings specific to the `omdStepVisualizer` component, controlling the appearance of step dots and text.
-
--   **`dotSizes`** {Object}
-    -   Defines the radius of the step dots based on their importance level.
-    -   **`level0`** {number}: Radius for major steps. Default: `8`.
-    -   **`level1`** {number}: Radius for minor steps. Default: `6`.
-    -   **`level2`** {number}: Radius for detailed steps. Default: `4`.
-
--   **`fontWeights`** {Object}
-    -   Defines the font weight for the equations based on their importance level.
-    -   **`level0`** {number}: Font weight for major steps. Default: `400`.
-    -   **`level1`** {number}: Font weight for minor steps. Default: `300`.
-    -   **`level2`** {number}: Font weight for detailed steps. Default: `200`.
-
-## Usage
-
-Configuration options can be set during initialization or updated at runtime using the `omdConfigManager` functions. For detailed usage, refer to the [`omdConfigManager`](./omdConfigManager.md) documentation.
-
-```javascript
-import { initializeConfig, setConfigValue, getConfigValue } from 'omd-library';
-
-// Initialize with a custom config file
-await initializeConfig('./my-custom-omd-config.json');
-
-// Or set options programmatically
-setConfigValue('multiplication.symbol', '*');
-setConfigValue('stepVisualizer.dotSizes.level0', 10);
-
-// Retrieve a config value
-const currentSymbol = getConfigValue('multiplication.symbol');
-console.log(currentSymbol); // Output: *
-```
+# Configuration Options
+
+This document details all available configuration options for the OMD library, managed by the `omdConfigManager` module. These options allow you to customize various aspects of the library's behavior, appearance, and mathematical preferences.
+
+## Overview
+
+The OMD configuration is a single JavaScript object that can be loaded from a JSON file or set programmatically. It is organized into logical categories.
+
+## Default Configuration Structure
+
+If no custom configuration is provided, the library uses the following default structure:
+
+```json
+{
+    "multiplication": {
+        "symbol": "·",
+        "forceImplicit": false,
+        "implicitCombinations": {
+            "constantVariable": true,
+            "variableConstant": false,
+            "parenthesisAfterVariable": true,
+            "parenthesisAfterConstant": true,
+            "variableParenthesis": true,
+            "parenthesisParenthesis": true,
+            "parenthesisVariable": true,
+            "parenthesisConstant": true,
+            "variableVariable": true
+        }
+    },
+    "stepVisualizer": {
+        "dotSizes": {
+            "level0": 8,
+            "level1": 6,
+            "level2": 4
+        },
+        "fontWeights": {
+            "level0": 400,
+            "level1": 400,
+            "level2": 400
+        }
+    }
+}
+```
+
+## Configuration Categories and Options
+
+### `multiplication`
+
+Settings related to how multiplication is displayed and handled.
+
+-   **`symbol`** {string}
+    -   The character used to represent multiplication. Default: `"·"` (middle dot).
+    -   Example: `"*"` or `"×"`.
+
+-   **`forceImplicit`** {boolean}
+    -   If `true`, implicit multiplication (e.g., `2x` instead of `2 * x`) is always used where mathematically valid, overriding `implicitCombinations`.
+    -   Default: `false`.
+
+-   **`implicitCombinations`** {Object}
+    -   An object defining specific scenarios where implicit multiplication should be used. Each property is a boolean.
+    -   **`constantVariable`** {boolean}: `2x` (Default: `true`)
+    -   **`variableConstant`** {boolean}: `x2` (Default: `false`)
+    -   **`parenthesisAfterVariable`** {boolean}: `x(y+z)` (Default: `true`)
+    -   **`parenthesisAfterConstant`** {boolean}: `2(x+y)` (Default: `true`)
+    -   **`variableParenthesis`** {boolean}: `(x+y)z` (Default: `true`)
+    -   **`parenthesisParenthesis`** {boolean}: `(x+y)(a+b)` (Default: `true`)
+    -   **`parenthesisVariable`** {boolean}: `(x+y)z` (Default: `true`)
+    -   **`parenthesisConstant`** {boolean}: `(x+y)2` (Default: `true`)
+    -   **`variableVariable`** {boolean}: `xy` (Default: `true`)
+
+### `stepVisualizer`
+
+Settings specific to the `omdStepVisualizer` component, controlling the appearance of step dots and text.
+
+-   **`dotSizes`** {Object}
+    -   Defines the radius of the step dots based on their importance level.
+    -   **`level0`** {number}: Radius for major steps. Default: `8`.
+    -   **`level1`** {number}: Radius for minor steps. Default: `6`.
+    -   **`level2`** {number}: Radius for detailed steps. Default: `4`.
+
+-   **`fontWeights`** {Object}
+    -   Defines the font weight for the equations based on their importance level.
+    -   **`level0`** {number}: Font weight for major steps. Default: `400`.
+    -   **`level1`** {number}: Font weight for minor steps. Default: `400`.
+    -   **`level2`** {number}: Font weight for detailed steps. Default: `400`.
+
+## Usage
+
+Configuration options can be set during initialization or updated at runtime using the `omdConfigManager` functions.
+
+### `initializeConfig(configSource)`
+
+Initializes the configuration by loading it from a file or object. This should be called early in the application lifecycle.
+
+-   **`configSource`** {string|Object} (optional) - The path to a JSON configuration file or a configuration object.
+
+```javascript
+import { initializeConfig } from '@teachinglab/omd';
+
+// Initialize with a custom config file
+await initializeConfig('./my-custom-omd-config.json');
+```
+
+### `setConfig(config)`
+
+Sets the configuration directly, bypassing file loading.
+
+-   **`config`** {Object} - A configuration object.
+
+```javascript
+import { setConfig } from '@teachinglab/omd';
+
+setConfig({
+    multiplication: {
+        symbol: '*'
+    }
+});
+```
+
+### `getDefaultConfig()`
+
+Returns a copy of the default configuration object.
+
+-   **Returns** {Object} - The default configuration.
+
+### `isEnabled(category, setting)`
+
+Checks if a specific feature is enabled in the configuration.
+
+-   **`category`** {string} - The configuration category (e.g., 'multiplication').
+-   **`setting`** {string} - The specific setting to check.
+-   **Returns** {boolean} - `true` if the setting is enabled, `false` otherwise.
+
+### `useImplicitMultiplication(combination)`
+
+Checks if implicit multiplication should be used for a specific combination of terms.
+
+-   **`combination`** {string} (optional) - The type of combination (e.g., 'constantVariable'). If not provided, it checks the `forceImplicit` setting.
+-   **Returns** {boolean} - `true` if implicit multiplication should be used.
+
+### `getMultiplicationSymbol()`
+
+Returns the configured multiplication symbol.
+
+-   **Returns** {string} - The multiplication symbol.
+
+### `updateConfig(category, setting, value)`
+
+Updates a configuration setting at runtime.
+
+-   **`category`** {string} - The configuration category.
+-   **`setting`** {string} - The setting to update.
+-   **`value`** {any} - The new value.
+
+### `getConfigValue(path)`
+
+Retrieves a configuration value using a dot-separated path.
+
+-   **`path`** {string} - The path to the value (e.g., 'multiplication.symbol').
+-   **Returns** {any} - The configuration value.
+
+### `setConfigValue(path, value)`
+
+Sets a configuration value using a dot-separated path.
+
+-   **`path`** {string} - The path to the value.
+-   **`value`** {any} - The new value.
+
+### `resetConfig()`
+
+Resets the configuration to its default state. Note: In the current implementation, this throws an error and advises to edit the `omdConfig.json` file directly.
+
+### `reloadConfig()`
+
+Reloads the configuration from the JSON file.
+
+-   **Returns** {Promise<Object>} - A promise that resolves to the reloaded configuration object.
+
+### `getConfigAsync()`
+
+Asynchronously retrieves the configuration object, loading it if necessary.
+
+-   **Returns** {Promise<Object>} - A promise that resolves to the configuration object.
+
+### `getDotRadius(level)`
+
+Gets the dot radius for a given step level in the step visualizer.
+
+-   **`level`** {number} (optional, default: 0) - The step level (0, 1, or 2).
+-   **Returns** {number} - The dot radius.
+
+### `getFontWeight(level)`
+
+Gets the font weight for a given step level in the step visualizer.
+
+-   **`level`** {number} (optional, default: 0) - The step level (0, 1, or 2).
+-   **Returns** {number} - The font weight.
+

package/docs/api/eventManager.md

@@ -1,68 +1,83 @@
-# EventManager
-
-The `EventManager` class is responsible for handling all user interactions with the canvas, including pointer events (mouse, touch, pen), keyboard events, and wheel events. It normals these events and delegates them to the appropriate handlers, such as the active tool or the `pointerEventHandler`.
-
-## Class Definition
-
-```javascript
-export class EventManager {
-    // ...
-}
-```
-
-## Constructor
-
-### `new EventManager(canvas)`
-
-Creates a new `EventManager` instance.
-
-*   **canvas** (`OMDCanvas`): The canvas instance.
-
-## Public Methods
-
-### `initialize()`
-
-Initializes the event manager and attaches all necessary event listeners to the canvas and document.
-
-### `getPointerInfo()`
-
-Gets information about the current state of the pointers.
-
-*   **Returns**: `object` - An object containing pointer information, including the number of active pointers and whether the user is currently drawing.
-
-### `destroy()`
-
-Destroys the event manager and removes all event listeners.
-
-## Event Handling
-
-The `EventManager` listens for the following events:
-
-*   **Pointer Events**: `pointerdown`, `pointermove`, `pointerup`, `pointercancel`, `pointerenter`, `pointerleave`
-*   **Keyboard Events**: `keydown`, `keyup`
-*   **Wheel Events**: `wheel`
-*   **Context Menu**: `contextmenu`
-
-When an event occurs, the `EventManager` normalizes it and then delegates it to the appropriate handler. For example, pointer events are passed to the `pointerEventHandler` and the active tool, while keyboard events are used to trigger global shortcuts or are passed to the active tool.
-
-## State Management
-
-The `EventManager` tracks the following state:
-
-*   **`activePointers`**: A map of all currently active pointers on the canvas.
-*   **`isDrawing`**: A boolean indicating whether a drawing operation is currently in progress.
-*   **`lastEventTime`**: The timestamp of the last processed event, used for throttling.
-
-## Event Emitters
-
-The `EventManager` also emits the following events on the canvas instance:
-
-*   `pointerDown`
-*   `pointerMove`
-*   `pointerUp`
-*   `pointerCancel`
-*   `pointerEnter`
-*   `pointerLeave`
-*   `keyDown`
-*   `keyUp`
-*   `wheel`
+# EventManager
+
+The `EventManager` class is the central hub for all user interactions with the OMD canvas. It is responsible for listening to raw browser events, normalizing them into a consistent format, and delegating them to the appropriate handlers, such as the active tool (`PencilTool`, `SelectTool`, etc.) or the `pointerEventHandler` for panning and zooming.
+
+## Class Definition
+
+```javascript
+export class EventManager {
+    // ...
+}
+```
+
+## Constructor
+
+### `new EventManager(canvas)`
+
+Creates a new `EventManager` instance.
+
+-   **`canvas`** (`OMDCanvas`): The main canvas instance to which this event manager is attached.
+
+## Public Methods
+
+### `initialize()`
+
+Binds all necessary event listeners to the canvas's SVG element and the document. This includes listeners for pointer events, keyboard events, and the mouse wheel. It also sets the `touch-action: none;` style on the SVG element to prevent default touch behaviors like scrolling.
+
+### `getPointerInfo()`
+
+Retrieves the current state of the pointers.
+
+-   **Returns**: `object` - An object containing:
+    -   `activePointers` {number}: The number of currently active pointers.
+    -   `isDrawing` {boolean}: Whether a drawing operation is in progress.
+    -   `multiTouch` {boolean}: Whether a multi-touch interaction is occurring.
+
+### `destroy()`
+
+Removes all event listeners and cleans up the event manager. This should be called when the canvas is no longer in use.
+
+## Event Handling Workflow
+
+The `EventManager` follows a clear workflow for handling events:
+
+1.  **Capture Raw Event**: Listens for native browser events (`pointerdown`, `keydown`, etc.).
+2.  **Prevent Default**: Calls `event.preventDefault()` for most events to stop the browser's default behavior (e.g., text selection, page scrolling).
+3.  **Normalize Event**: Converts the raw event object into a standardized format. For pointer events, this includes converting screen coordinates to SVG coordinates and normalizing pressure values (see `_normalizePointerEvent`).
+4.  **Delegate to Handlers**: Passes the normalized event to the relevant handlers:
+    -   **`pointerEventHandler`**: For core interactions like panning and zooming.
+    -   **Active Tool**: The currently selected tool (e.g., `PencilTool`) receives the event to perform its specific function (e.g., drawing a line).
+5.  **Emit Canvas Event**: Emits a high-level event on the canvas instance (e.g., `pointerDown`, `keyDown`) that other parts of the application can listen to.
+
+## Pointer Event Handler
+
+The `EventManager` uses an instance of `pointerEventHandler` to manage view transformations like panning and zooming, which are typically initiated with multi-touch gestures or mouse wheel interactions.
+
+## Private Methods (Internal Logic)
+
+The following methods handle the internal logic of the `EventManager`. While you won't call them directly, understanding their role can be helpful for debugging or extending the library.
+
+-   **`_onPointerDown(event)`**: Handles the start of a pointer interaction. It tracks the active pointer, sets pointer capture, and delegates to the appropriate handlers.
+-   **`_onPointerMove(event)`**: Handles pointer movement. It throttles events to maintain performance, updates the cursor position, and delegates to handlers if a drawing is in progress.
+-   **`_onPointerUp(event)`**: Handles the end of a pointer interaction. It cleans up the active pointer and notifies the active tool that the stroke has finished.
+-   **`_onPointerCancel(event)`**: Handles cases where a pointer interaction is unexpectedly terminated.
+-   **`_onPointerEnter(event)` / `_onPointerLeave(event)`**: Manages the visibility of the custom cursor as the pointer enters and leaves the canvas.
+-   **`_onKeyDown(event)` / `_onKeyUp(event)`**: Handles keyboard input, checking for global shortcuts (like switching tools) before delegating to the active tool.
+-   **`_onWheel(event)`**: Handles mouse wheel events, typically for zooming.
+-   **`_onContextMenu(event)`**: Prevents the browser's context menu from appearing over the canvas.
+-   **`_normalizePointerEvent(event, canvasCoords)`**: Converts a raw pointer event into a normalized object with consistent properties (e.g., `x`, `y`, `pressure`).
+-   **`_normalizePressure(pressure)`**: Clamps the pointer pressure value to a range between 0 and 1, providing a default value for devices without pressure sensitivity.
+
+## Emitted Events
+
+The `EventManager` emits the following events on the `OMDCanvas` instance, allowing other modules to react to user input:
+
+-   `pointerDown`
+-   `pointerMove`
+-   `pointerUp`
+-   `pointerCancel`
+-   `pointerEnter`
+-   `pointerLeave`
+-   `keyDown`
+-   `keyUp`
+-   `wheel`