# OMD (Open Math Display)

> A JavaScript library for creating interactive mathematical interfaces in web applications

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.

## Quick Start

### Installation

    npm install @teachinglab/omd

### Basic Usage

    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 - Get up and running with OMD
- Quick Examples - Common use cases and code snippets
- Factory Functions - Creating objects from JSON (AI-friendly)

### Core Concepts

#### 1. Global Context & Configuration

Learn about the foundational systems that power OMD:

- Configuration Manager - Library-wide settings and theming
- Configuration Options - Complete list of available settings
- Display System - Main rendering engine
- Canvas System - Multi-expression layout manager
- Event Manager - Event handling and coordination
- Helpers & Utilities - Utility functions for common tasks

#### 2. Visualizations

Interactive visual components for teaching and learning:

##### Number & Ratio Visualizations

- Number Line - `omdNumberLine` - Interactive number lines with dots and labels
- Number Tiles - `omdNumberTile` - Visual counting tiles with dots
- Tape Diagrams - `omdTapeDiagram` - Part-whole relationship diagrams
- Ratio Charts - `omdRatioChart` - Pie and bar chart ratio visualizations
- Balance Hanger - `omdBalanceHanger` - Balance scale visualizations

##### Graphing & Geometry

- Coordinate Plane - `omdCoordinatePlane` - 2D graphing with functions and shapes
- Shapes - `omdShapes` - Geometric shapes (circles, rectangles, polygons, triangles)
- Spinner - `omdSpinner` - Interactive circular spinners

##### Data Display

- Tables - `omdTable` - Data tables with customizable styling
- Function Graphs - Plotting mathematical functions

#### 3. Equations & Expressions

The heart of mathematical notation and manipulation:

##### Core Expression Components

- Expression Nodes - Understanding the node tree structure and omdEquationNode class
- omdEquationNode - Complete equations with manipulation methods (e.g., `2x + 3 = 11`)
- omdExpression - Mathematical expressions (e.g., `3x² + 5`)
- omdTerm - Individual terms (e.g., `3x²`)
- omdNumber - Numeric constants
- omdVariable - Variables (e.g., `x`, `y`)
- omdOperator - Mathematical operators (+, -, ×, ÷)

##### Advanced Expression Types

- omdPowerExpression - Exponentiation (e.g., `(x+1)²`)
- omdRationalExpression - Fractions (e.g., `(x+1)/(x-1)`)
- omdFunction - Mathematical functions (e.g., `f(x) = 2x + 1`)
- omdTileEquation - Visual tile-based equations

##### Step-by-Step Solutions

- Equation Stack - Sequenced solution steps
- Step Visualizer - Interactive step visualization
- Simplification Engine - Rule-based expression simplification
- Simplification Rules - Available transformation rules

### Complete API Reference

- Full API Documentation - Complete reference for all components
- JSON Schemas - Detailed JSON structure for all components

## 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

## Guides

### By Use Case

- Creating Equations - Work with equations and expressions
- Visualizations Guide - All visualization components
- Step-by-Step Solutions - Building interactive solutions
- Interactive Features - Drag & drop, toolbars, and more

### Advanced Topics

- Expression Tree Structure - Understanding the AST
- Custom Simplification Rules - Extending the simplification engine
- Theming & Styling - Customizing appearance
- Performance Optimization - 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)

## Examples

### Creating Objects from JSON (Factory Method)

    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);

### Basic Equation

    import { omdDisplay, omdEquationNode } from '@teachinglab/omd';

    const display = new omdDisplay(document.getElementById('container'));
    const equation = omdEquationNode.fromString('2x + 3 = 11');
    display.render(equation);

### Step-by-Step Solution

    import { omdEquationStack } from '@teachinglab/omd';

    const steps = [
        '2x + 3 = 11',
        '2x = 8',
        'x = 4'
    ];

    const stack = new omdEquationStack(steps.map(s =>
        omdEquationNode.fromString(s)
    ), {
        toolbar: true,
        stepVisualizer: true
    });

    display.render(stack);

### Coordinate Plane with Function

    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);

### Number Line Visualization

    import { omdNumberLine } from '@teachinglab/omd';

    const numberLine = new omdNumberLine();
    numberLine.loadFromJSON({
        min: 0,
        max: 10,
        dotValues: [2, 5, 8],
        label: 'Number Line Example'
    });

    display.render(numberLine);

## Dependencies

- JSVG (`@teachinglab/jsvg`) - High-performance SVG rendering
- math.js - Mathematical expression parsing
- Modern Browser - ES6 modules, SVG support required

## License

MIT License - see LICENSE for details

## Contributing

We welcome contributions! See our contributing guidelines for more information.

Ready to get started? Check out the Getting Started Guide or explore the JSON Schemas for detailed component configurations.

↑