@teachinglab/omd 0.5.7 → 0.6.0

package/npm-docs/guides/factory-functions.md

@@ -0,0 +1,354 @@
+# Factory Functions
+
+OMD provides factory functions to simplify creating objects from JSON data. This eliminates the need for large switch statements when working with dynamic data or AI-generated JSON.
+
+## createFromJSON
+
+The main factory function that creates OMD objects from JSON data.
+
+### Usage
+
+```javascript
+import { createFromJSON } from '@teachinglab/omd';
+
+const jsonData = {
+    omdType: 'numberLine',
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8]
+};
+
+const omdObject = createFromJSON(jsonData);
+```
+
+### Parameters
+
+- **jsonData** (object): JSON object with an `omdType` field and component-specific properties
+
+### Returns
+
+- **object**: The created OMD object with data already loaded via `loadFromJSON()`
+
+### Throws
+
+- **Error**: If `omdType` is missing or unsupported
+
+### Supported Types
+
+The factory supports all OMD visualization and mathematical components:
+
+**Visualizations:**
+- `balanceHanger`
+- `table`
+- `tapeDiagram`
+- `coordinatePlane`
+- `numberLine`
+- `numberTile`
+- `ratioChart`
+- `tileEquation`
+- `spinner`
+
+**Mathematical Components:**
+- `equation`
+- `expression`
+- `term`
+- `number`
+- `variable`
+- `powerExpression`
+- `rationalExpression`
+- `function`
+
+**Geometric Shapes:**
+- `rightTriangle`
+- `isoscelesTriangle`
+- `rectangle`
+- `ellipse`
+- `circle`
+- `regularPolygon`
+
+## Examples
+
+### Creating a Number Line
+
+```javascript
+import { createFromJSON } from '@teachinglab/omd';
+
+const numberLine = createFromJSON({
+    omdType: 'numberLine',
+    min: 0,
+    max: 20,
+    dotValues: [5, 10, 15],
+    label: 'Skip Counting by 5'
+});
+
+// Add to SVG
+const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+svg.setAttribute("width", numberLine.width);
+svg.setAttribute("height", numberLine.height);
+svg.appendChild(numberLine.svgObject);
+document.body.appendChild(svg);
+```
+
+### Creating a Coordinate Plane
+
+```javascript
+const plane = createFromJSON({
+    omdType: 'coordinatePlane',
+    xMin: -10,
+    xMax: 10,
+    yMin: -10,
+    yMax: 10,
+    graphEquations: [
+        { equation: 'y = x^2 - 4', color: '#e11d48', strokeWidth: 2 }
+    ]
+});
+```
+
+### Creating an Equation
+
+```javascript
+const equation = createFromJSON({
+    omdType: 'equation',
+    equation: '2x + 3 = 11'
+});
+```
+
+### Working with AI-Generated JSON
+
+The factory function is especially useful when working with AI-generated content:
+
+```javascript
+import { createFromJSON } from '@teachinglab/omd';
+
+async function generateVisualization(userRequest) {
+    // Call AI API
+    const response = await fetch(
+        `https://your-api.com/generate?topic=${encodeURIComponent(userRequest)}`
+    );
+    const jsonData = await response.json();
+    
+    // Create OMD object - no switch statement needed!
+    const omdObject = createFromJSON(jsonData);
+    
+    // Render to SVG
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("width", omdObject.width || 400);
+    svg.setAttribute("height", omdObject.height || 500);
+    svg.setAttribute("viewBox", omdObject.svgObject.getAttribute("viewBox"));
+    svg.appendChild(omdObject.svgObject);
+    
+    return svg;
+}
+
+// Usage
+const svg = await generateVisualization("number line from 0 to 10");
+document.getElementById('container').appendChild(svg);
+```
+
+## Helper Functions
+
+### getSupportedTypes
+
+Returns an array of all supported OMD types.
+
+```javascript
+import { getSupportedTypes } from '@teachinglab/omd';
+
+const types = getSupportedTypes();
+console.log(types);
+// ['balanceHanger', 'table', 'coordinatePlane', 'numberLine', ...]
+```
+
+### isTypeSupported
+
+Checks if a given type is supported.
+
+```javascript
+import { isTypeSupported } from '@teachinglab/omd';
+
+if (isTypeSupported('numberLine')) {
+    console.log('Number lines are supported!');
+}
+
+if (!isTypeSupported('customType')) {
+    console.log('This type is not supported');
+}
+```
+
+## Before and After
+
+### Before (Without Factory)
+
+```javascript
+import { 
+    omdBalanceHanger,
+    omdTable,
+    omdNumberLine,
+    // ... 20+ more imports
+} from '@teachinglab/omd';
+
+let omdObject;
+
+switch (jsonData.omdType) {
+    case 'balanceHanger':
+        omdObject = new omdBalanceHanger();
+        break;
+    case 'table':
+        omdObject = new omdTable();
+        break;
+    case 'numberLine':
+        omdObject = new omdNumberLine();
+        break;
+    // ... 20+ more cases
+    default:
+        throw new Error(`Unsupported type: ${jsonData.omdType}`);
+}
+
+omdObject.loadFromJSON(jsonData);
+```
+
+### After (With Factory)
+
+```javascript
+import { createFromJSON } from '@teachinglab/omd';
+
+const omdObject = createFromJSON(jsonData);
+```
+
+Much cleaner!
+
+## Error Handling
+
+The factory function provides clear error messages:
+
+```javascript
+import { createFromJSON } from '@teachinglab/omd';
+
+try {
+    // Missing omdType
+    const obj1 = createFromJSON({ min: 0, max: 10 });
+} catch (error) {
+    console.error(error.message);
+    // "JSON data must include an 'omdType' field"
+}
+
+try {
+    // Unsupported type
+    const obj2 = createFromJSON({ omdType: 'unknownType' });
+} catch (error) {
+    console.error(error.message);
+    // "Unsupported omdType: 'unknownType'. Supported types: balanceHanger, table, ..."
+}
+```
+
+## TypeScript Support
+
+If using TypeScript, you can type the return value:
+
+```typescript
+import { createFromJSON } from '@teachinglab/omd';
+import type { omdNumberLine } from '@teachinglab/omd';
+
+const jsonData = {
+    omdType: 'numberLine',
+    min: 0,
+    max: 10
+};
+
+const numberLine = createFromJSON(jsonData) as omdNumberLine;
+```
+
+## Best Practices
+
+### 1. Always Include omdType
+
+Ensure your JSON data includes the `omdType` field:
+
+```javascript
+const jsonData = {
+    omdType: 'coordinatePlane',  // Required!
+    xMin: -10,
+    xMax: 10
+};
+```
+
+### 2. Validate Types Before Creation
+
+For dynamic data, validate the type first:
+
+```javascript
+import { isTypeSupported, createFromJSON } from '@teachinglab/omd';
+
+if (isTypeSupported(jsonData.omdType)) {
+    const omdObject = createFromJSON(jsonData);
+} else {
+    console.error(`Type ${jsonData.omdType} is not supported`);
+}
+```
+
+### 3. Use with Display System
+
+Combine with the display system for easy rendering:
+
+```javascript
+import { createFromJSON, omdDisplay } from '@teachinglab/omd';
+
+const display = new omdDisplay(document.getElementById('container'));
+const omdObject = createFromJSON(jsonData);
+display.render(omdObject);
+```
+
+## Complete Example
+
+Here's a complete example integrating the factory with an AI API:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>OMD Factory Example</title>
+</head>
+<body>
+    <input type="text" id="input" placeholder="Describe what to visualize" />
+    <button id="generate">Generate</button>
+    <div id="container"></div>
+
+    <script type="module">
+        import { createFromJSON } from '@teachinglab/omd';
+        
+        document.getElementById('generate').addEventListener('click', async () => {
+            const request = document.getElementById('input').value;
+            
+            try {
+                // Get JSON from AI API
+                const response = await fetch(`/api/generate?q=${encodeURIComponent(request)}`);
+                const jsonData = await response.json();
+                
+                // Create OMD object
+                const omdObject = createFromJSON(jsonData);
+                
+                // Render to SVG
+                const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+                svg.setAttribute("width", omdObject.width || 400);
+                svg.setAttribute("height", omdObject.height || 500);
+                svg.setAttribute("viewBox", omdObject.svgObject.getAttribute("viewBox"));
+                svg.appendChild(omdObject.svgObject);
+                
+                // Add to page
+                document.getElementById('container').innerHTML = '';
+                document.getElementById('container').appendChild(svg);
+            } catch (error) {
+                console.error('Error:', error.message);
+            }
+        });
+    </script>
+</body>
+</html>
+```
+
+## See Also
+
+- [JSON Schemas](../json-schemas.md) - Complete JSON reference for all components
+- [Getting Started](./getting-started.md) - Basic setup and usage
+- [API Reference](../api/api-reference.md) - Detailed API documentation

package/npm-docs/guides/getting-started.md

@@ -0,0 +1,318 @@
+# Getting Started with OMD
+
+This guide will help you install and start using OMD (Open Math Display) in your project.
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @teachinglab/omd
+```
+
+### Using yarn
+
+```bash
+yarn add @teachinglab/omd
+```
+
+## Basic Setup
+
+### 1. Import OMD
+
+```javascript
+import { omdDisplay } from '@teachinglab/omd';
+```
+
+### 2. Create a Container
+
+Add a container element to your HTML:
+
+```html
+<div id="math-container"></div>
+```
+
+### 3. Initialize and Render
+
+```javascript
+// Get the container element
+const container = document.getElementById('math-container');
+
+// Create a display instance
+const display = new omdDisplay(container);
+
+// Render an equation
+display.render('2x + 3 = 11');
+```
+
+## Complete Example
+
+Here's a complete HTML file with OMD:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>OMD Example</title>
+    <style>
+        body {
+            font-family: 'Albert Sans', sans-serif;
+            padding: 20px;
+        }
+        #math-container {
+            width: 100%;
+            height: 400px;
+            border: 1px solid #ccc;
+            border-radius: 8px;
+        }
+    </style>
+</head>
+<body>
+    <h1>My First OMD App</h1>
+    <div id="math-container"></div>
+    
+    <script type="module">
+        import { omdDisplay, omdEquationNode } from '@teachinglab/omd';
+        
+        const container = document.getElementById('math-container');
+        const display = new omdDisplay(container);
+        
+        // Create and render an equation
+        const equation = omdEquationNode.fromString('2x + 3 = 11');
+        display.render(equation);
+    </script>
+</body>
+</html>
+```
+
+## Common Use Cases
+
+### Rendering Different Components
+
+#### 1. Simple Equation
+
+```javascript
+import { omdDisplay } from '@teachinglab/omd';
+
+const display = new omdDisplay(container);
+display.render('x + 5 = 10');
+```
+
+#### 2. Expression
+
+```javascript
+import { omdExpression } from '@teachinglab/omd';
+
+const expr = new omdExpression();
+expr.loadFromJSON("3x^2 + 5x - 2");
+display.render(expr);
+```
+
+#### 3. Number Line
+
+```javascript
+import { omdNumberLine } from '@teachinglab/omd';
+
+const numberLine = new omdNumberLine();
+numberLine.loadFromJSON({
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8],
+    label: "Number Line"
+});
+display.render(numberLine);
+```
+
+#### 4. Coordinate Plane
+
+```javascript
+import { omdCoordinatePlane } from '@teachinglab/omd';
+
+const plane = new omdCoordinatePlane();
+plane.loadFromJSON({
+    xMin: -10,
+    xMax: 10,
+    yMin: -10,
+    yMax: 10,
+    graphEquations: [
+        { equation: 'y = x^2', color: '#e11d48', strokeWidth: 2 }
+    ]
+});
+display.render(plane);
+```
+
+#### 5. Step-by-Step Solution
+
+```javascript
+import { omdEquationStack, omdEquationNode } from '@teachinglab/omd';
+
+const steps = [
+    omdEquationNode.fromString('2x + 3 = 11'),
+    omdEquationNode.fromString('2x = 8'),
+    omdEquationNode.fromString('x = 4')
+];
+
+const stack = new omdEquationStack(steps, {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+display.render(stack);
+```
+
+## Configuration
+
+### Display Options
+
+You can configure the display when creating it:
+
+```javascript
+const display = new omdDisplay(container, {
+    fontSize: 36,
+    centerContent: true,
+    fontFamily: 'Albert Sans'
+});
+```
+
+### Global Configuration
+
+OMD uses a global configuration manager:
+
+```javascript
+import { omdConfigManager } from '@teachinglab/omd';
+
+// Update global settings
+omdConfigManager.setConfig({
+    defaultFontSize: 32,
+    defaultColor: '#333333',
+    highlightColor: '#FFD700'
+});
+```
+
+## Loading from JSON
+
+Most OMD components can be loaded from JSON:
+
+```javascript
+import { omdTable } from '@teachinglab/omd';
+
+const table = new omdTable();
+table.loadFromJSON({
+    equation: "y = x^2",
+    headers: ["x", "y"],
+    xMin: -5,
+    xMax: 5,
+    stepSize: 1,
+    title: "Quadratic Function"
+});
+
+display.render(table);
+```
+
+See the [JSON Schemas documentation](../json-schemas.md) for complete JSON specifications.
+
+## Using with Build Tools
+
+### Vite
+
+OMD works seamlessly with Vite:
+
+```javascript
+// main.js
+import { omdDisplay } from '@teachinglab/omd';
+
+const display = new omdDisplay(document.getElementById('app'));
+display.render('2x + 3 = 11');
+```
+
+### Webpack
+
+Configure Webpack to handle ES modules:
+
+```javascript
+// webpack.config.js
+module.exports = {
+    // ... other config
+    resolve: {
+        extensions: ['.js']
+    }
+};
+```
+
+### React
+
+OMD can be used with React using refs:
+
+```jsx
+import React, { useEffect, useRef } from 'react';
+import { omdDisplay } from '@teachinglab/omd';
+
+function MathComponent() {
+    const containerRef = useRef(null);
+    
+    useEffect(() => {
+        if (containerRef.current) {
+            const display = new omdDisplay(containerRef.current);
+            display.render('2x + 3 = 11');
+        }
+    }, []);
+    
+    return <div ref={containerRef} style={{ width: '100%', height: '400px' }} />;
+}
+
+export default MathComponent;
+```
+
+## Next Steps
+
+Now that you have OMD installed and working, explore these resources:
+
+1. **[Visualizations Guide](./visualizations.md)** - Learn about all visual components
+2. **[Equations Guide](./equations.md)** - Master equations and expressions
+3. **[JSON Schemas](../json-schemas.md)** - Complete component reference
+4. **[API Reference](../api/api-reference.md)** - Detailed API documentation
+5. **[Examples](./quick-examples.md)** - More code examples
+
+## Troubleshooting
+
+### Module not found
+
+If you get "Module not found" errors, ensure:
+- OMD is installed: `npm install @teachinglab/omd`
+- Your bundler supports ES modules
+- Import paths are correct
+
+### Display not rendering
+
+If the display doesn't appear:
+- Check that the container element exists in the DOM
+- Ensure the container has width and height
+- Check browser console for errors
+
+### Style issues
+
+For best results:
+- Use `Albert Sans` font family
+- Ensure adequate container dimensions
+- Check that SVG rendering is supported in your browser
+
+## Browser Support
+
+OMD requires:
+- Modern browser with ES6 support
+- SVG rendering capabilities
+- Native ES modules or a bundler
+
+Tested on:
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Getting Help
+
+- **GitHub Issues**: Report bugs or request features
+- **Documentation**: Browse the complete [API Reference](../api/api-reference.md)
+- **Examples**: Check the repository's `/examples` directory