@teachinglab/omd 0.5.8 → 0.6.0

package/README.md

@@ -1,9 +1,101 @@
-# OMD (Open Math Display)
+# OMD (On-screen Math Display)
 
-OMD is a JavaScript library for creating interactive mathematical interfaces in web applications. Build everything from simple equation displays to complex step-by-step solution systems with rich visual feedback and user interaction.
+> A JavaScript library for creating interactive mathematical interfaces in web applications
+
+[![npm version](https://img.shields.io/npm/v/@teachinglab/omd.svg)](https://www.npmjs.com/package/@teachinglab/omd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OMD is a comprehensive JavaScript library for building rich, interactive mathematical experiences in the browser. From simple equation displays to complex step-by-step solution systems with full visual feedback and user interaction.
 
 ![OMD Demo](https://i.imgur.com/CdtEi33.png)
 
+## Quick Start
+
+### Installation
+
+```bash
+npm install @teachinglab/omd
+```
+
+### Basic Usage
+
+```javascript
+import { omdDisplay } from '@teachinglab/omd';
+
+// Create a math display
+const container = document.getElementById('math-container');
+const display = new omdDisplay(container);
+
+// Render an equation
+display.render('2x + 3 = 11');
+```
+
+## Documentation
+
+### Getting Started
+- **[Installation & Setup](./guides/getting-started.md)** - Get up and running with OMD
+- **[Quick Examples](./guides/quick-examples.md)** - Common use cases and code snippets
+- **[Factory Functions](./guides/factory-functions.md)** - Creating objects from JSON (AI-friendly)
+
+### Core Concepts
+
+#### 1. Global Context & Configuration
+Learn about the foundational systems that power OMD:
+
+- **[Configuration Manager](./api/omdConfigManager.md)** - Library-wide settings and theming
+- **[Configuration Options](./api/configuration-options.md)** - Complete list of available settings
+- **[Display System](./api/omdDisplay.md)** - Main rendering engine
+- **[Canvas System](./api/omdCanvas.md)** - Multi-expression layout manager
+- **[Event Manager](./api/eventManager.md)** - Event handling and coordination
+- **[Helpers & Utilities](./api/omdHelpers.md)** - Utility functions for common tasks
+
+#### 2. Visualizations
+Interactive visual components for teaching and learning:
+
+##### Number & Ratio Visualizations
+- **[Number Line](./guides/visualizations.md#number-line)** - `omdNumberLine` - Interactive number lines with dots and labels
+- **[Number Tiles](./guides/visualizations.md#number-tiles)** - `omdNumberTile` - Visual counting tiles with dots
+- **[Tape Diagrams](./guides/visualizations.md#tape-diagrams)** - `omdTapeDiagram` - Part-whole relationship diagrams
+- **[Ratio Charts](./guides/visualizations.md#ratio-charts)** - `omdRatioChart` - Pie and bar chart ratio visualizations
+- **[Balance Hanger](./guides/visualizations.md#balance-hanger)** - `omdBalanceHanger` - Balance scale visualizations
+
+##### Graphing & Geometry
+- **[Coordinate Plane](./guides/visualizations.md#coordinate-plane)** - `omdCoordinatePlane` - 2D graphing with functions and shapes
+- **[Shapes](./guides/visualizations.md#shapes)** - `omdShapes` - Geometric shapes (circles, rectangles, polygons, triangles)
+- **[Spinner](./guides/visualizations.md#spinner)** - `omdSpinner` - Interactive circular spinners
+
+##### Data Display
+- **[Tables](./guides/visualizations.md#tables)** - `omdTable` - Data tables with customizable styling
+- **[Function Graphs](./guides/visualizations.md#function-graphs)** - Plotting mathematical functions
+
+#### 3. Equations & Expressions
+The heart of mathematical notation and manipulation:
+
+##### Core Expression Components
+- **[Expression Nodes](./api/expression-nodes.md)** - Understanding the node tree structure and omdEquationNode class
+- **[omdEquationNode](./api/omdEquationNode.md)** - Complete equations with manipulation methods (e.g., `2x + 3 = 11`)
+- **[omdExpression](./guides/equations.md#expressions)** - Mathematical expressions (e.g., `3x² + 5`)
+- **[omdTerm](./guides/equations.md#terms)** - Individual terms (e.g., `3x²`)
+- **[omdNumber](./guides/equations.md#numbers)** - Numeric constants
+- **[omdVariable](./guides/equations.md#variables)** - Variables (e.g., `x`, `y`)
+- **[omdOperator](./guides/equations.md#operators)** - Mathematical operators (+, -, ×, ÷)
+
+##### Advanced Expression Types
+- **[omdPowerExpression](./guides/equations.md#power-expressions)** - Exponentiation (e.g., `(x+1)²`)
+- **[omdRationalExpression](./guides/equations.md#rational-expressions)** - Fractions (e.g., `(x+1)/(x-1)`)
+- **[omdFunction](./guides/equations.md#functions)** - Mathematical functions (e.g., `f(x) = 2x + 1`)
+- **[omdTileEquation](./guides/equations.md#tile-equations)** - Visual tile-based equations
+
+##### Step-by-Step Solutions
+- **[Equation Stack](./api/omdEquationStack.md)** - Sequenced solution steps
+- **[Step Visualizer](./api/omdStepVisualizer.md)** - Interactive step visualization
+- **[Simplification Engine](./api/omdSimplification.md)** - Rule-based expression simplification
+- **[Simplification Rules](./api/simplificationRules.md)** - Available transformation rules
+
+### Complete API Reference
+- **[Full API Documentation](./api/api-reference.md)** - Complete reference for all components
+- **[JSON Schemas](./json-schemas.md)** - Detailed JSON structure for all components
+
 ## Features
 
 ### **Interactive Math Rendering**
@@ -26,38 +118,82 @@ OMD is a JavaScript library for creating interactive mathematical interfaces in
 - Progressive step revelation
 - Visual operation feedback and highlighting
 
-## Installation
+## Guides
 
-### npm
-```bash
-npm install @teachinglab/omd
+### By Use Case
+- **[Creating Equations](./guides/equations.md)** - Work with equations and expressions
+- **[Visualizations Guide](./guides/visualizations.md)** - All visualization components
+- **[Step-by-Step Solutions](./guides/step-by-step.md)** - Building interactive solutions
+- **[Interactive Features](./guides/interactive-features.md)** - Drag & drop, toolbars, and more
+
+### Advanced Topics
+- **[Expression Tree Structure](./guides/expression-tree.md)** - Understanding the AST
+- **[Custom Simplification Rules](./guides/custom-rules.md)** - Extending the simplification engine
+- **[Theming & Styling](./guides/theming.md)** - Customizing appearance
+- **[Performance Optimization](./guides/performance.md)** - Best practices for large applications
+
+## Architecture
+
+```
+OMD Library Structure
+├── Core Systems
+│   ├── Configuration Manager (Global settings)
+│   ├── Display System (Rendering engine)
+│   └── Event Manager (Coordination)
+│
+├── Visualizations
+│   ├── Number Visualizations (Number line, tiles, tape diagrams)
+│   ├── Graphing (Coordinate plane, functions)
+│   └── Data Display (Tables, charts)
+│
+└── Equations & Expressions
+    ├── Node System (Expression tree)
+    ├── Equation Components (Equations, terms, operators)
+    ├── Advanced Expressions (Powers, rationals, functions)
+    └── Step-by-Step System (Simplification, visualization)
 ```
 
-## Basic Usage
+## Examples
+
+### Creating Objects from JSON (Factory Method)
+
 ```javascript
-import { omdDisplay } from '@teachinglab/omd';
+import { createFromJSON } from '@teachinglab/omd';
+
+// AI-generated or dynamic JSON data
+const jsonData = {
+    omdType: 'numberLine',
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8]
+};
+
+// Create the object - no switch statement needed!
+const numberLine = createFromJSON(jsonData);
+```
 
-// Create a math display
-const container = document.getElementById('math-container');
-const display = new omdDisplay(container);
+### Basic Equation
+```javascript
+import { omdDisplay, omdEquationNode } from '@teachinglab/omd';
 
-// Render an equation
-display.render('2x + 3 = 11');
+const display = new omdDisplay(document.getElementById('container'));
+const equation = omdEquationNode.fromString('2x + 3 = 11');
+display.render(equation);
 ```
 
-### Step-by-Step Solutions
+### Step-by-Step Solution
 ```javascript
-import { omdEquationStack, omdEquationNode } from '@teachinglab/omd';
+import { omdEquationStack } from '@teachinglab/omd';
 
-// Create solution steps
 const steps = [
-    omdEquationNode.fromString('2x + 3 = 11'),
-    omdEquationNode.fromString('2x = 8'),
-    omdEquationNode.fromString('x = 4')
+    '2x + 3 = 11',
+    '2x = 8',
+    'x = 4'
 ];
 
-// Create interactive equation stack
-const stack = new omdEquationStack(steps, {
+const stack = new omdEquationStack(steps.map(s => 
+    omdEquationNode.fromString(s)
+), {
     toolbar: true,
     stepVisualizer: true
 });
@@ -65,74 +201,51 @@ const stack = new omdEquationStack(steps, {
 display.render(stack);
 ```
 
-## Core Concepts
-
-### **Nodes** - Building Blocks
-Every mathematical element is a node in an expression tree:
-- `omdEquationNode` - Complete equations (e.g., `2x + 3 = 11`)
-- `omdConstantNode` - Numbers (e.g., `5`, `3.14`)
-- `omdVariableNode` - Variables (e.g., `x`, `y`)
-- `omdBinaryExpressionNode` - Operations (e.g., `+`, `-`, `*`, `/`)
-
-### **Sequences** - Solution Steps
-Group related equations for step-by-step solving:
+### Coordinate Plane with Function
 ```javascript
-const sequence = new omdEquationSequenceNode([
-    equation1, equation2, equation3
-]);
+import { omdCoordinatePlane } from '@teachinglab/omd';
+
+const plane = new omdCoordinatePlane();
+plane.loadFromJSON({
+    xMin: -10, xMax: 10,
+    yMin: -10, yMax: 10,
+    graphEquations: [
+        { equation: 'y = x^2 - 4', color: '#e11d48', strokeWidth: 2 }
+    ]
+});
+
+display.render(plane);
 ```
 
-### **Display** - Rendering Engine
-Handles layout, centering, and visualization:
+### Number Line Visualization
 ```javascript
-const display = new omdDisplay(container, {
-    fontSize: 36,
-    centerContent: true
+import { omdNumberLine } from '@teachinglab/omd';
+
+const numberLine = new omdNumberLine();
+numberLine.loadFromJSON({
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8],
+    label: 'Number Line Example'
 });
-```
-
-## Interactive Examples
-
-Explore OMD's capabilities with our comprehensive examples:
-
-| Category | Example | Description |
-|----------|---------|-------------|
-| **Getting Started** | [Minimal](examples/minimal.html) | Basic equation rendering |
-| | [Simple Usage](examples/simple-usage.html) | Interactive features |
-| **Advanced** | [Expression Playground](examples/expression-playground.html) | Full manipulation interface |
-| | [Drag & Drop](examples/drag-and-drop-playground.html) | Intuitive interaction |
-| **Educational** | [Worked Solutions](examples/worked-solution.html) | Step-by-step solving |
-| | [Kids Interactive](examples/kids-interactive.html) | Child-friendly interface |
-| **Components** | [Equation Stack](examples/equation-stack-test.html) | Stacked equations |
-| | [Canvas Demo](examples/canvas-multiple-nodes.html) | Multi-expression layouts |
 
-**[Browse All Examples](examples/index.html)**
-
-## Documentation
+display.render(numberLine);
+```
 
-| Resource | Description |
-|----------|-------------|
-| **[API Reference](docs/api-reference.md)** | Complete component documentation |
-| **[User Guide](docs/user-guide.md)** | Getting started and tutorials |
+## Dependencies
 
+- **JSVG** (`@teachinglab/jsvg`) - High-performance SVG rendering
+- **math.js** - Mathematical expression parsing
+- **Modern Browser** - ES6 modules, SVG support required
 
-## Architecture
+## License
 
-```
-OMD Library Structure
-├── Display Layer (omdDisplay)
-├── Node System (Expression tree components)
-├── UI Components (Toolbar, Step visualizer)
-├── Core Systems (Simplification, Layout)
-└── Utilities (Configuration, Helpers)
-```
+MIT License - see [LICENSE](../LICENSE) for details
 
-## Dependencies
+## Contributing
 
-- **JSVG** - High-performance SVG rendering
-- **math.js** - Mathematical expression parsing
-- **Modern Browser** - ES6 modules, SVG support
+We welcome contributions! See our [contributing guidelines](../CONTRIBUTING.md) for more information.
 
 ---
 
-**Ready to get started?** Check out our [examples](examples/index.html) or dive into the [documentation](docs/api-reference.md)!
+**Ready to get started?** Check out the [Getting Started Guide](./guides/getting-started.md) or explore the [JSON Schemas](./json-schemas.md) for detailed component configurations.

package/README.old.md

@@ -0,0 +1,138 @@
+# OMD (Open Math Display)
+
+OMD is a JavaScript library for creating interactive mathematical interfaces in web applications. Build everything from simple equation displays to complex step-by-step solution systems with rich visual feedback and user interaction.
+
+![OMD Demo](https://i.imgur.com/CdtEi33.png)
+
+## Features
+
+### **Interactive Math Rendering**
+- High-quality SVG-based mathematical notation
+- Real-time expression manipulation and visualization
+- Automatic layout and alignment for complex equations
+
+### **Step-by-Step Solutions**
+- Visual step tracking with detailed explanations
+- Simplification engine with rule-based transformations
+- Provenance tracking for highlighting related elements
+
+### **Rich UI Components**
+- Built-in toolbar for common mathematical operations
+- Drag & drop interface for intuitive manipulation
+- Customizable canvas for multi-expression layouts
+
+### **Educational Features**
+- Interactive learning experiences
+- Progressive step revelation
+- Visual operation feedback and highlighting
+
+## Installation
+
+### npm
+```bash
+npm install @teachinglab/omd
+```
+
+## Basic Usage
+```javascript
+import { omdDisplay } from '@teachinglab/omd';
+
+// Create a math display
+const container = document.getElementById('math-container');
+const display = new omdDisplay(container);
+
+// Render an equation
+display.render('2x + 3 = 11');
+```
+
+### Step-by-Step Solutions
+```javascript
+import { omdEquationStack, omdEquationNode } from '@teachinglab/omd';
+
+// Create solution steps
+const steps = [
+    omdEquationNode.fromString('2x + 3 = 11'),
+    omdEquationNode.fromString('2x = 8'),
+    omdEquationNode.fromString('x = 4')
+];
+
+// Create interactive equation stack
+const stack = new omdEquationStack(steps, {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+display.render(stack);
+```
+
+## Core Concepts
+
+### **Nodes** - Building Blocks
+Every mathematical element is a node in an expression tree:
+- `omdEquationNode` - Complete equations (e.g., `2x + 3 = 11`)
+- `omdConstantNode` - Numbers (e.g., `5`, `3.14`)
+- `omdVariableNode` - Variables (e.g., `x`, `y`)
+- `omdBinaryExpressionNode` - Operations (e.g., `+`, `-`, `*`, `/`)
+
+### **Sequences** - Solution Steps
+Group related equations for step-by-step solving:
+```javascript
+const sequence = new omdEquationSequenceNode([
+    equation1, equation2, equation3
+]);
+```
+
+### **Display** - Rendering Engine
+Handles layout, centering, and visualization:
+```javascript
+const display = new omdDisplay(container, {
+    fontSize: 36,
+    centerContent: true
+});
+```
+
+## Interactive Examples
+
+Explore OMD's capabilities with our comprehensive examples:
+
+| Category | Example | Description |
+|----------|---------|-------------|
+| **Getting Started** | [Minimal](examples/minimal.html) | Basic equation rendering |
+| | [Simple Usage](examples/simple-usage.html) | Interactive features |
+| **Advanced** | [Expression Playground](examples/expression-playground.html) | Full manipulation interface |
+| | [Drag & Drop](examples/drag-and-drop-playground.html) | Intuitive interaction |
+| **Educational** | [Worked Solutions](examples/worked-solution.html) | Step-by-step solving |
+| | [Kids Interactive](examples/kids-interactive.html) | Child-friendly interface |
+| **Components** | [Equation Stack](examples/equation-stack-test.html) | Stacked equations |
+| | [Canvas Demo](examples/canvas-multiple-nodes.html) | Multi-expression layouts |
+
+**[Browse All Examples](examples/index.html)**
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| **[API Reference](docs/api-reference.md)** | Complete component documentation |
+| **[User Guide](docs/user-guide.md)** | Getting started and tutorials |
+
+
+## Architecture
+
+```
+OMD Library Structure
+├── Display Layer (omdDisplay)
+├── Node System (Expression tree components)
+├── UI Components (Toolbar, Step visualizer)
+├── Core Systems (Simplification, Layout)
+└── Utilities (Configuration, Helpers)
+```
+
+## Dependencies
+
+- **JSVG** - High-performance SVG rendering
+- **math.js** - Mathematical expression parsing
+- **Modern Browser** - ES6 modules, SVG support
+
+---
+
+**Ready to get started?** Check out our [examples](examples/index.html) or dive into the [documentation](docs/api-reference.md)!

package/npm-docs/DOCUMENTATION_SUMMARY.md

@@ -2,7 +2,7 @@
 
 This document provides an overview of the organized NPM documentation structure for the OMD library.
 
-## 📁 Folder Structure
+## Folder Structure
 
 ```
 npm-docs/
@@ -18,7 +18,7 @@ npm-docs/
     └── [individual component docs]    # Copied from docs/api/
 ```
 
-## 📖 Documentation Organization
+## Documentation Organization
 
 The documentation follows the requested presentation order:
 
@@ -62,7 +62,7 @@ The documentation follows the requested presentation order:
      - Step Visualizer
      - Simplification Engine
 
-## 🚀 Quick Navigation
+## Quick Navigation
 
 ### For New Users
 1. **Start Here**: `README.md`
@@ -75,7 +75,7 @@ The documentation follows the requested presentation order:
 3. **Equations**: `guides/equations.md`
 4. **API Details**: `api/api-reference.md`
 
-## 📝 Key Files
+## Key Files
 
 ### README.md
 - **Purpose**: Main entry point for NPM documentation
@@ -138,7 +138,7 @@ The documentation follows the requested presentation order:
   - Advanced features
   - Complete working HTML example
 
-## ✅ Verification Checklist
+## Verification Checklist
 
 - [x] Main README.md created with proper organization
 - [x] json-schemas.md corrected and verified
@@ -149,7 +149,7 @@ The documentation follows the requested presentation order:
 - [x] API documentation copied to npm-docs/api
 - [x] Documentation follows requested order: Global Context → Visualizations → Equations
 
-## 🎯 Next Steps (Before Publishing)
+## Next Steps (Before Publishing)
 
 1. **Review the documentation**:
    - Check `npm-docs/README.md` for accuracy
@@ -181,7 +181,7 @@ The documentation follows the requested presentation order:
    npm publish
    ```
 
-## 📋 Documentation Standards Used
+## Documentation Standards Used
 
 - **Markdown formatting**: Proper headings, code blocks, tables
 - **Code examples**: Syntax-highlighted JavaScript
@@ -193,28 +193,28 @@ The documentation follows the requested presentation order:
 - **Navigation aids**: Table of contents, cross-references
 - **Accessibility**: Clear descriptions, organized content
 
-## 🔗 Internal Link Structure
+## Internal Link Structure
 
 All documentation files are cross-linked:
 - README.md → All guides and API docs
 - Each guide → Related guides and API reference
 - json-schemas.md → API reference and guides
 
-## 📊 Coverage
+## Coverage
 
 The documentation covers:
-- ✅ All visualization components
-- ✅ All equation components
-- ✅ Configuration system
-- ✅ Step-by-step solution system
-- ✅ JSON schemas for all components
-- ✅ Installation and setup
-- ✅ Integration guides (React, Vite, Webpack)
-- ✅ Best practices
-- ✅ Troubleshooting
+- All visualization components
+- All equation components
+- Configuration system
+- Step-by-step solution system
+- JSON schemas for all components
+- Installation and setup
+- Integration guides (React, Vite, Webpack)
+- Best practices
+- Troubleshooting
 
 ---
 
-**Documentation Status**: ✅ Complete and ready for review
+**Documentation Status**: Complete and ready for review
 
 **Do NOT publish to NPM until reviewed and approved!**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teachinglab/omd",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "omd",
   "main": "./index.js",
   "module": "./index.js",
@@ -14,9 +14,9 @@
     "src/",
     "omd/",
     "docs/",
-    "npm-docs/",
     "canvas/",
-    "jsvg/"
+    "jsvg/"  ,
+    "npm-docs/"
   ],
   "keywords": [
     "math",
@@ -31,7 +31,6 @@
   "license": "MIT",
   "dependencies": {
     "@teachinglab/jsvg": "^0.1.1",
-    "@teachinglab/omd": "^0.5.4",
     "mathjs": "^14.5.2"
   },
   "scripts": {
@@ -54,3 +53,4 @@
     "vite": "^5.4.0"
   }
 }
+