@teachinglab/omd 0.5.7 → 0.5.8

package/npm-docs/guides/visualizations.md

@@ -0,0 +1,682 @@
+# Visualizations Guide
+
+OMD provides a comprehensive set of visualization components for teaching and learning mathematics. This guide covers all visualization components organized by category.
+
+## Table of Contents
+
+1. [Number & Ratio Visualizations](#number--ratio-visualizations)
+2. [Graphing & Geometry](#graphing--geometry)
+3. [Data Display](#data-display)
+
+---
+
+## Number & Ratio Visualizations
+
+### Number Line
+
+`omdNumberLine` creates interactive number lines with labeled ticks and optional dots to mark values.
+
+#### Basic Usage
+
+```javascript
+import { omdNumberLine } from '@teachinglab/omd';
+
+const numberLine = new omdNumberLine();
+numberLine.loadFromJSON({
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8],
+    label: "Number Line"
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min` | number | 0 | Minimum value on the line |
+| `max` | number | 10 | Maximum value on the line |
+| `dotValues` | number[] | [] | Array of values to mark with dots |
+| `label` | string | "" | Optional label for the number line |
+
+#### Examples
+
+**Simple number line (0-20):**
+```javascript
+numberLine.loadFromJSON({
+    min: 0,
+    max: 20
+});
+```
+
+**Marking fractions:**
+```javascript
+numberLine.loadFromJSON({
+    min: 0,
+    max: 1,
+    dotValues: [0.25, 0.5, 0.75],
+    label: "Fractions"
+});
+```
+
+**Negative numbers:**
+```javascript
+numberLine.loadFromJSON({
+    min: -10,
+    max: 10,
+    dotValues: [-5, 0, 5]
+});
+```
+
+---
+
+### Number Tiles
+
+`omdNumberTile` creates visual tiles with dots for counting and grouping activities.
+
+#### Basic Usage
+
+```javascript
+import { omdNumberTile } from '@teachinglab/omd';
+
+const tile = new omdNumberTile();
+tile.loadFromJSON({
+    value: 10,
+    size: "medium",
+    dotsPerColumn: 5
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | number | required | Number of dots to display |
+| `size` | "small" \| "medium" \| "large" | "medium" | Size of the tile |
+| `dotsPerColumn` | number | 5 | How many dots per column |
+| `backgroundColor` | string | "#FFFFFF" | Background color of tile |
+| `dotColor` | string | "#000000" | Color of the dots |
+
+#### Examples
+
+**Small tile:**
+```javascript
+tile.loadFromJSON({
+    value: 5,
+    size: "small",
+    backgroundColor: "#E8F4FD",
+    dotColor: "#1976D2"
+});
+```
+
+**Custom arrangement:**
+```javascript
+tile.loadFromJSON({
+    value: 15,
+    dotsPerColumn: 3,  // 5 columns x 3 rows
+    size: "large"
+});
+```
+
+---
+
+### Tape Diagrams
+
+`omdTapeDiagram` creates part-whole relationship diagrams with labeled sections.
+
+#### Basic Usage
+
+```javascript
+import { omdTapeDiagram } from '@teachinglab/omd';
+
+const tape = new omdTapeDiagram();
+tape.loadFromJSON({
+    values: [3, 5, 2],
+    colors: ["#FF6B6B", "#4ECDC4", "#45B7D1"],
+    labelSet: [
+        {
+            startIndex: 0,
+            endIndex: 2,
+            label: "Total: 10",
+            showBelow: true
+        }
+    ]
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `values` | number[] | required | Array of segment values |
+| `showValues` | boolean | true | Show values in each segment |
+| `colors` | string[] | auto | Colors for each segment |
+| `labelSet` | TapeLabel[] | [] | Labels spanning segments |
+| `unitWidth` | number | 30 | Width per unit value |
+
+#### Label Structure
+
+```typescript
+{
+    startIndex: number,    // First segment index
+    endIndex: number,      // Last segment index
+    label: string,         // Label text
+    showBelow?: boolean    // Show below the tape
+}
+```
+
+#### Examples
+
+**Simple ratio:**
+```javascript
+tape.loadFromJSON({
+    values: [2, 3],
+    colors: ["#FF6B6B", "#4ECDC4"],
+    labelSet: [
+        { startIndex: 0, endIndex: 1, label: "2:3", showBelow: true }
+    ]
+});
+```
+
+**Multi-part problem:**
+```javascript
+tape.loadFromJSON({
+    values: [4, 4, 4, 6],
+    showValues: true,
+    labelSet: [
+        { startIndex: 0, endIndex: 2, label: "3 equal parts" },
+        { startIndex: 3, endIndex: 3, label: "remainder" }
+    ],
+    unitWidth: 25
+});
+```
+
+---
+
+### Ratio Charts
+
+`omdRatioChart` creates pie and bar chart visualizations for ratios.
+
+#### Basic Usage
+
+```javascript
+import { omdRatioChart } from '@teachinglab/omd';
+
+const chart = new omdRatioChart();
+chart.loadFromJSON({
+    valueA: 3,
+    valueB: 2,
+    renderType: "pie",
+    size: "medium"
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `valueA` | number | required | First ratio value |
+| `valueB` | number | required | Second ratio value |
+| `renderType` | "pie" \| "bar" | "pie" | Chart type |
+| `size` | "small" \| "medium" \| "large" | "medium" | Chart size |
+
+#### Examples
+
+**Pie chart:**
+```javascript
+chart.loadFromJSON({
+    valueA: 3,
+    valueB: 5,
+    renderType: "pie"
+});
+```
+
+**Bar chart:**
+```javascript
+chart.loadFromJSON({
+    valueA: 7,
+    valueB: 3,
+    renderType: "bar",
+    size: "large"
+});
+```
+
+---
+
+### Balance Hanger
+
+`omdBalanceHanger` creates balance scale visualizations for equations and equality.
+
+#### Basic Usage
+
+```javascript
+import { omdBalanceHanger } from '@teachinglab/omd';
+
+const balance = new omdBalanceHanger();
+balance.loadFromJSON({
+    leftValues: [5, 3],
+    rightValues: [4, 4],
+    tilt: "balanced"
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `leftValues` | number[] | required | Values on left side |
+| `rightValues` | number[] | required | Values on right side |
+| `tilt` | "left" \| "right" \| "balanced" | auto | Balance state |
+
+#### Examples
+
+**Balanced equation:**
+```javascript
+balance.loadFromJSON({
+    leftValues: [10],
+    rightValues: [7, 3],
+    tilt: "balanced"
+});
+```
+
+**Unbalanced:**
+```javascript
+balance.loadFromJSON({
+    leftValues: [8, 3],
+    rightValues: [5, 2],
+    tilt: "left"
+});
+```
+
+---
+
+## Graphing & Geometry
+
+### Coordinate Plane
+
+`omdCoordinatePlane` creates a 2D coordinate system with full graphing capabilities.
+
+#### Basic Usage
+
+```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 }
+    ]
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `xMin` | number | -5 | Minimum x value |
+| `xMax` | number | 5 | Maximum x value |
+| `yMin` | number | -5 | Minimum y value |
+| `yMax` | number | 5 | Maximum y value |
+| `xLabel` | string | "" | X-axis label |
+| `yLabel` | string | "" | Y-axis label |
+| `tickInterval` | number | 1 | Spacing between ticks |
+| `graphEquations` | Equation[] | [] | Functions to graph |
+| `lineSegments` | LineSegment[] | [] | Line segments to draw |
+| `dotValues` | Dot[] | [] | Points to plot |
+| `shapeSet` | Shape[] | [] | Shapes to display |
+| `showTickLabels` | boolean | true | Show numeric labels |
+| `backgroundColor` | string | lightGray | Background color |
+| `showBackground` | boolean | true | Show background |
+
+#### Equation Structure
+
+```typescript
+{
+    equation: string,      // e.g., "y = 2x + 1"
+    color?: string,        // Line color
+    strokeWidth?: number,  // Line width
+    domain?: {             // Optional domain restriction
+        min: number,
+        max: number
+    }
+}
+```
+
+#### Examples
+
+**Linear function:**
+```javascript
+plane.loadFromJSON({
+    xMin: -5,
+    xMax: 5,
+    yMin: -5,
+    yMax: 5,
+    graphEquations: [
+        { equation: 'y = 2x + 1', color: '#3B82F6', strokeWidth: 2 }
+    ],
+    xLabel: "x",
+    yLabel: "y"
+});
+```
+
+**Multiple functions:**
+```javascript
+plane.loadFromJSON({
+    xMin: -10,
+    xMax: 10,
+    yMin: -10,
+    yMax: 10,
+    graphEquations: [
+        { equation: 'y = x^2', color: '#e11d48', strokeWidth: 2 },
+        { equation: 'y = 2x + 1', color: '#3B82F6', strokeWidth: 2 },
+        { equation: 'y = -x^2 + 5', color: '#10B981', strokeWidth: 2 }
+    ]
+});
+```
+
+**With points and shapes:**
+```javascript
+plane.loadFromJSON({
+    xMin: -5,
+    xMax: 5,
+    yMin: -5,
+    yMax: 5,
+    graphEquations: [
+        { equation: 'y = x^2 - 4', color: '#e11d48' }
+    ],
+    dotValues: [
+        [-2, 0, "blue"],  // [x, y, color]
+        [2, 0, "blue"],
+        [0, -4, "red"]
+    ],
+    lineSegments: [
+        {
+            point1: [-2, 0],
+            point2: [2, 0],
+            color: "green",
+            strokeWidth: 1
+        }
+    ]
+});
+```
+
+---
+
+### Shapes
+
+OMD provides several geometric shapes that can be used standalone or within a coordinate plane.
+
+#### Circle
+
+```javascript
+import { omdCircle } from '@teachinglab/omd';
+
+const circle = new omdCircle();
+circle.loadFromJSON({
+    radius: 10,
+    color: "#FF0000"
+});
+```
+
+#### Rectangle
+
+```javascript
+import { omdRectangle } from '@teachinglab/omd';
+
+const rect = new omdRectangle();
+rect.loadFromJSON({
+    width: 20,
+    height: 10,
+    color: "#00FF00"
+});
+```
+
+#### Regular Polygon
+
+```javascript
+import { omdRegularPolygon } from '@teachinglab/omd';
+
+const polygon = new omdRegularPolygon();
+polygon.loadFromJSON({
+    sides: 6,      // Hexagon
+    radius: 15,
+    color: "#0000FF"
+});
+```
+
+#### Ellipse
+
+```javascript
+import { omdEllipse } from '@teachinglab/omd';
+
+const ellipse = new omdEllipse();
+ellipse.loadFromJSON({
+    radiusX: 20,
+    radiusY: 10,
+    color: "#FFFF00"
+});
+```
+
+#### Right Triangle
+
+```javascript
+import { omdRightTriangle } from '@teachinglab/omd';
+
+const triangle = new omdRightTriangle();
+triangle.loadFromJSON({
+    base: 10,
+    height: 15,
+    color: "#FF00FF"
+});
+```
+
+#### Isosceles Triangle
+
+```javascript
+import { omdIsoscelesTriangle } from '@teachinglab/omd';
+
+const triangle = new omdIsoscelesTriangle();
+triangle.loadFromJSON({
+    base: 10,
+    height: 15,
+    color: "#00FFFF"
+});
+```
+
+#### Using Shapes in Coordinate Plane
+
+```javascript
+plane.loadFromJSON({
+    xMin: -5,
+    xMax: 5,
+    yMin: -5,
+    yMax: 5,
+    shapeSet: [
+        { omdType: 'circle', radius: 2, color: '#FF6B6B' },
+        { omdType: 'rectangle', width: 3, height: 2, color: '#4ECDC4' },
+        { omdType: 'regularPolygon', sides: 6, radius: 1.5, color: '#45B7D1' }
+    ]
+});
+```
+
+---
+
+### Spinner
+
+`omdSpinner` creates circular spinners for probability and division activities.
+
+#### Basic Usage
+
+```javascript
+import { omdSpinner } from '@teachinglab/omd';
+
+const spinner = new omdSpinner();
+spinner.loadFromJSON({
+    divisions: 8,
+    arrowPosition: 3,
+    size: "medium"
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `divisions` | number | required | Number of spinner divisions |
+| `arrowPosition` | number | 0 | Initial arrow position |
+| `size` | "small" \| "medium" \| "large" | "medium" | Spinner size |
+
+#### Examples
+
+**Four equal parts:**
+```javascript
+spinner.loadFromJSON({
+    divisions: 4,
+    arrowPosition: 0
+});
+```
+
+**Probability spinner:**
+```javascript
+spinner.loadFromJSON({
+    divisions: 10,
+    arrowPosition: 5,
+    size: "large"
+});
+```
+
+---
+
+## Data Display
+
+### Tables
+
+`omdTable` creates data tables with customizable styling.
+
+#### Basic Usage
+
+```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"
+});
+```
+
+#### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `equation` | string | "" | Equation to generate data |
+| `data` | [number, number][] | [] | Manual data input |
+| `headers` | string[] | ['x', 'y'] | Column headers |
+| `xMin` | number | -5 | Minimum x value |
+| `xMax` | number | 5 | Maximum x value |
+| `stepSize` | number | 1 | Increment between x values |
+| `title` | string | "" | Table title |
+| `fontSize` | number | 14 | Cell font size |
+| `headerFontSize` | number | 16 | Header font size |
+| `fontFamily` | string | "Albert Sans" | Font family |
+| `cellHeight` | number | 35 | Cell height in pixels |
+| `backgroundColor` | string | lightGray | Background color |
+| `alternatingRowColors` | string[] | null | Alternating row colors |
+
+#### Examples
+
+**From equation:**
+```javascript
+table.loadFromJSON({
+    equation: "y = 2x + 1",
+    headers: ["x", "y"],
+    xMin: -3,
+    xMax: 3,
+    stepSize: 1,
+    title: "Linear Function",
+    alternatingRowColors: ["#F0F0F0", "#FFFFFF"]
+});
+```
+
+**Manual data:**
+```javascript
+table.loadFromJSON({
+    data: [
+        [0, 0],
+        [1, 1],
+        [2, 4],
+        [3, 9]
+    ],
+    headers: ["x", "x²"],
+    title: "Squares",
+    fontSize: 16,
+    cellHeight: 40
+});
+```
+
+**Styled table:**
+```javascript
+table.loadFromJSON({
+    equation: "y = x^3",
+    xMin: -2,
+    xMax: 2,
+    stepSize: 0.5,
+    title: "Cubic Function",
+    fontFamily: "Georgia",
+    fontSize: 14,
+    headerFontSize: 18,
+    backgroundColor: "#E3F2FD",
+    alternatingRowColors: ["#BBDEFB", "#E3F2FD"]
+});
+```
+
+---
+
+## Best Practices
+
+### Sizing
+
+Most visualization components support size options:
+- `"small"` - Compact display
+- `"medium"` - Standard size (default)
+- `"large"` - Expanded display
+
+### Colors
+
+OMD uses a consistent color system:
+- Use hex colors for consistency: `#FF6B6B`
+- Access built-in colors: `omdColor.lightGray`
+- Ensure sufficient contrast for accessibility
+
+### Performance
+
+For coordinate planes with many equations:
+- Limit the number of simultaneous graphs
+- Use domain restrictions when possible
+- Consider the viewport size (xMin/xMax, yMin/yMax)
+
+### Responsive Design
+
+Set appropriate container dimensions:
+```css
+#math-container {
+    width: 100%;
+    max-width: 800px;
+    height: 400px;
+}
+```
+
+## Next Steps
+
+- **[Equations Guide](./equations.md)** - Learn about equation components
+- **[JSON Schemas](../json-schemas.md)** - Complete reference
+- **[API Reference](../api/api-reference.md)** - Detailed documentation
+- **[Examples](./quick-examples.md)** - More code samples