@teachinglab/omd 0.5.6 → 0.5.8

package/npm-docs/json-schemas.md

@@ -0,0 +1,826 @@
+# JSON Schemas for OMD Components
+
+This document provides complete JSON schemas and examples for all OMD visual components. Use these with the `loadFromJSON()` method.
+
+## Table of Contents
+
+1. [Global Context & Configuration](#global-context--configuration)
+2. [Visualizations](#visualizations)
+   - [Number & Ratio Visualizations](#number--ratio-visualizations)
+   - [Graphing & Geometry](#graphing--geometry)
+   - [Data Display](#data-display)
+3. [Equations & Expressions](#equations--expressions)
+   - [Core Components](#core-components)
+   - [Advanced Expressions](#advanced-expressions)
+
+---
+
+## Global Context & Configuration
+
+### Common Expression Format
+
+Many components accept expressions in multiple formats:
+
+**String Format** (simplest):
+```javascript
+"2x + 3"
+```
+
+**Structured Format** (programmatic):
+```json
+{
+  "termsAndOpers": [
+    { "omdType": "term", "coefficient": 2, "variable": "x", "exponent": 1 },
+    { "omdType": "operator", "operator": "+" },
+    { "omdType": "number", "value": 3 }
+  ]
+}
+```
+
+### Primitive Types
+
+#### `omdNumber`
+```json
+{
+  "omdType": "number",
+  "value": 42
+}
+```
+
+#### `omdVariable`
+```json
+{
+  "omdType": "variable",
+  "name": "x"
+}
+```
+
+#### `omdOperator`
+```json
+{
+  "omdType": "operator",
+  "operator": "+"
+}
+```
+Supported operators: `+`, `-`, `/`, `÷`, `x`, `*`, `•`, `×`, `=`
+
+#### `omdTerm`
+```json
+{
+  "omdType": "term",
+  "coefficient": 3,
+  "variable": "x",
+  "exponent": 2
+}
+```
+
+---
+
+## Visualizations
+
+### Number & Ratio Visualizations
+
+#### `omdNumberLine`
+
+Interactive number line with labeled ticks and optional dots.
+
+**Schema:**
+```typescript
+{
+  min: number,
+  max: number,
+  dotValues?: number[],
+  label?: string
+}
+```
+
+**Example:**
+```json
+{
+  "min": 0,
+  "max": 10,
+  "dotValues": [2, 5, 8],
+  "label": "Number Line Example"
+}
+```
+
+**Usage:**
+```javascript
+const numberLine = new omdNumberLine();
+numberLine.loadFromJSON({
+  min: 0,
+  max: 10,
+  dotValues: [2, 5, 8],
+  label: "Number Line Example"
+});
+```
+
+---
+
+#### `omdNumberTile`
+
+Visual tile with dots for counting and grouping activities.
+
+**Schema:**
+```typescript
+{
+  value: number,
+  size?: "small" | "medium" | "large",
+  dotsPerColumn?: number,
+  backgroundColor?: string,
+  dotColor?: string
+}
+```
+
+**Example:**
+```json
+{
+  "value": 10,
+  "size": "medium",
+  "dotsPerColumn": 5,
+  "backgroundColor": "#FFFFFF",
+  "dotColor": "#000000"
+}
+```
+
+---
+
+#### `omdTapeDiagram`
+
+Part-whole relationship diagrams with labeled sections.
+
+**Schema:**
+```typescript
+{
+  values: number[],
+  showValues?: boolean,
+  colors?: string[],
+  labelSet?: Array<{
+    startIndex: number,
+    endIndex: number,
+    label: string,
+    showBelow?: boolean
+  }>,
+  unitWidth?: number
+}
+```
+
+**Example:**
+```json
+{
+  "values": [1, 2, 3],
+  "showValues": true,
+  "colors": ["#FF0000", "#00FF00", "#0000FF"],
+  "labelSet": [
+    {
+      "startIndex": 0,
+      "endIndex": 2,
+      "label": "Total: 6",
+      "showBelow": true
+    }
+  ],
+  "unitWidth": 30
+}
+```
+
+---
+
+#### `omdRatioChart`
+
+Pie and bar chart ratio visualizations.
+
+**Schema:**
+```typescript
+{
+  valueA: number,
+  valueB: number,
+  renderType?: "pie" | "bar",
+  size?: "small" | "medium" | "large"
+}
+```
+
+**Example:**
+```json
+{
+  "valueA": 3,
+  "valueB": 2,
+  "renderType": "pie",
+  "size": "medium"
+}
+```
+
+---
+
+#### `omdBalanceHanger`
+
+Balance scale visualizations.
+
+**Schema:**
+```typescript
+{
+  leftValues: number[],
+  rightValues: number[],
+  tilt?: "left" | "right" | "balanced"
+}
+```
+
+**Example:**
+```json
+{
+  "leftValues": [5, 3],
+  "rightValues": [4, 4],
+  "tilt": "balanced"
+}
+```
+
+---
+
+### Graphing & Geometry
+
+#### `omdCoordinatePlane`
+
+2D coordinate plane with axes, gridlines, functions, shapes, and plots.
+
+**Schema:**
+```typescript
+{
+  graphEquations?: Array<{
+    equation: string,
+    color?: string,
+    strokeWidth?: number,
+    domain?: { min: number, max: number }
+  }>,
+  lineSegments?: Array<{
+    point1: [number, number],
+    point2: [number, number],
+    color?: string,
+    strokeWidth?: number
+  }>,
+  dotValues?: Array<[number, number, string?]>,
+  shapeSet?: Array<ShapeObject>,
+  xMin?: number,
+  xMax?: number,
+  yMin?: number,
+  yMax?: number,
+  xLabel?: string,
+  yLabel?: string,
+  axisLabelOffsetPx?: number,
+  size?: "small" | "medium" | "large",
+  tickInterval?: number,
+  forceAllTickLabels?: boolean,
+  tickLabelOffsetPx?: number,
+  showTickLabels?: boolean,
+  backgroundColor?: string,
+  backgroundCornerRadius?: number,
+  backgroundOpacity?: number,
+  showBackground?: boolean
+}
+```
+
+**Example:**
+```json
+{
+  "graphEquations": [
+    {
+      "equation": "y = x^2 - 4",
+      "color": "#e11d48",
+      "strokeWidth": 2,
+      "domain": { "min": -5, "max": 5 }
+    }
+  ],
+  "lineSegments": [
+    {
+      "point1": [0, 0],
+      "point2": [1, 1],
+      "color": "red",
+      "strokeWidth": 2
+    }
+  ],
+  "dotValues": [[0, 0, "green"], [1, 1, "blue"]],
+  "xMin": -5,
+  "xMax": 5,
+  "yMin": -5,
+  "yMax": 5,
+  "xLabel": "X-Axis",
+  "yLabel": "Y-Axis",
+  "tickInterval": 1,
+  "showTickLabels": true,
+  "backgroundColor": "#FFFFFF",
+  "showBackground": true
+}
+```
+
+---
+
+#### `omdShapes`
+
+Geometric shapes for visualization.
+
+**Circle:**
+```json
+{
+  "omdType": "circle",
+  "radius": 10,
+  "color": "#FF0000"
+}
+```
+
+**Rectangle:**
+```json
+{
+  "omdType": "rectangle",
+  "width": 20,
+  "height": 10,
+  "color": "#00FF00"
+}
+```
+
+**Regular Polygon:**
+```json
+{
+  "omdType": "regularPolygon",
+  "sides": 6,
+  "radius": 15,
+  "color": "#0000FF"
+}
+```
+
+**Ellipse:**
+```json
+{
+  "omdType": "ellipse",
+  "radiusX": 20,
+  "radiusY": 10,
+  "color": "#FFFF00"
+}
+```
+
+**Right Triangle:**
+```json
+{
+  "omdType": "rightTriangle",
+  "base": 10,
+  "height": 15,
+  "color": "#FF00FF"
+}
+```
+
+**Isosceles Triangle:**
+```json
+{
+  "omdType": "isoscelesTriangle",
+  "base": 10,
+  "height": 15,
+  "color": "#00FFFF"
+}
+```
+
+---
+
+#### `omdSpinner`
+
+Circular spinner for divisions and selections.
+
+**Schema:**
+```typescript
+{
+  divisions: number,
+  arrowPosition: number,
+  size?: "small" | "medium" | "large"
+}
+```
+
+**Example:**
+```json
+{
+  "divisions": 8,
+  "arrowPosition": 3,
+  "size": "medium"
+}
+```
+
+---
+
+### Data Display
+
+#### `omdTable`
+
+Tabular data display with customizable styling.
+
+**Schema:**
+```typescript
+{
+  equation?: string,
+  data?: Array<[number, number]>,
+  headers?: string[],
+  xMin?: number,
+  xMax?: number,
+  stepSize?: number,
+  title?: string,
+  fontSize?: number,
+  headerFontSize?: number,
+  fontFamily?: string,
+  headerFontFamily?: string,
+  cellHeight?: number,
+  headerHeight?: number,
+  minCellWidth?: number,
+  maxCellWidth?: number,
+  padding?: number,
+  backgroundColor?: string,
+  backgroundCornerRadius?: number,
+  backgroundOpacity?: number,
+  showBackground?: boolean,
+  alternatingRowColors?: string[]
+}
+```
+
+**Example:**
+```json
+{
+  "equation": "y = x^2",
+  "headers": ["x", "y"],
+  "xMin": -5,
+  "xMax": 5,
+  "stepSize": 1,
+  "title": "Quadratic Table",
+  "fontSize": 14,
+  "headerFontSize": 16,
+  "fontFamily": "Albert Sans",
+  "cellHeight": 35,
+  "backgroundColor": "#FFFFFF",
+  "alternatingRowColors": ["#F0F0F0", "#FFFFFF"]
+}
+```
+
+---
+
+## Equations & Expressions
+
+### Core Components
+
+#### `omdEquation`
+
+Complete mathematical equations with left and right sides.
+
+**Schema (String Form):**
+```json
+{
+  "equation": "2x + 3 = 11"
+}
+```
+
+**Schema (Structured Form):**
+```typescript
+{
+  leftExpression: Expression | string,
+  rightExpression: Expression | string,
+  equation?: string
+}
+```
+
+**Examples:**
+```json
+{
+  "equation": "2x + 3 = 11"
+}
+```
+
+```json
+{
+  "leftExpression": {
+    "termsAndOpers": [
+      { "omdType": "term", "coefficient": 2, "variable": "x" },
+      { "omdType": "operator", "operator": "+" },
+      { "omdType": "number", "value": 3 }
+    ]
+  },
+  "rightExpression": {
+    "omdType": "number",
+    "value": 11
+  }
+}
+```
+
+**Usage:**
+```javascript
+// Simple string form
+const eq = new omdEquation();
+eq.loadFromJSON({ equation: '2x + 3 = 11' });
+
+// Structured form
+eq.loadFromJSON({
+  leftExpression: { omdType: 'term', coefficient: 2, variable: 'x' },
+  rightExpression: { omdType: 'number', value: 11 }
+});
+```
+
+---
+
+#### `omdExpression`
+
+Mathematical expressions (terms and operators).
+
+**Schema (String Form):**
+```javascript
+"3x^2 + 5x - 2"
+```
+
+**Schema (Structured Form):**
+```typescript
+{
+  termsAndOpers: Array<Term | Number | Variable | Operator>
+}
+```
+
+**Example:**
+```json
+{
+  "termsAndOpers": [
+    { "omdType": "term", "coefficient": 3, "variable": "x", "exponent": 2 },
+    { "omdType": "operator", "operator": "+" },
+    { "omdType": "term", "coefficient": 5, "variable": "x", "exponent": 1 },
+    { "omdType": "operator", "operator": "-" },
+    { "omdType": "number", "value": 2 }
+  ]
+}
+```
+
+---
+
+#### `omdString`
+
+Simple string value for labels or annotations.
+
+**Schema:**
+```typescript
+{
+  name: string
+}
+```
+
+**Example:**
+```json
+{
+  "name": "Example Label"
+}
+```
+
+---
+
+### Advanced Expressions
+
+#### `omdPowerExpression`
+
+Expressions raised to a power (exponentiation).
+
+**Schema:**
+```typescript
+{
+  baseExpression: Expression | string,
+  exponentExpression: Expression | string
+}
+```
+
+**Example:**
+```json
+{
+  "baseExpression": {
+    "termsAndOpers": [
+      { "omdType": "variable", "name": "x" },
+      { "omdType": "operator", "operator": "+" },
+      { "omdType": "number", "value": 1 }
+    ]
+  },
+  "exponentExpression": {
+    "omdType": "number",
+    "value": 2
+  }
+}
+```
+
+**Renders as:** `(x + 1)²`
+
+---
+
+#### `omdRationalExpression`
+
+Fractions and rational expressions.
+
+**Schema:**
+```typescript
+{
+  numeratorExpression: Expression | string,
+  denominatorExpression: Expression | string
+}
+```
+
+**Example:**
+```json
+{
+  "numeratorExpression": {
+    "termsAndOpers": [
+      { "omdType": "variable", "name": "x" },
+      { "omdType": "operator", "operator": "+" },
+      { "omdType": "number", "value": 1 }
+    ]
+  },
+  "denominatorExpression": {
+    "termsAndOpers": [
+      { "omdType": "variable", "name": "x" },
+      { "omdType": "operator", "operator": "-" },
+      { "omdType": "number", "value": 1 }
+    ]
+  }
+}
+```
+
+**Renders as:** `(x + 1)/(x - 1)`
+
+---
+
+#### `omdFunction`
+
+Mathematical functions with named inputs.
+
+**Schema:**
+```typescript
+{
+  name: string,
+  inputVariables: string[],
+  expression: Expression | string
+}
+```
+
+**Example:**
+```json
+{
+  "name": "f",
+  "inputVariables": ["x"],
+  "expression": {
+    "termsAndOpers": [
+      { "omdType": "term", "coefficient": 2, "variable": "x" },
+      { "omdType": "operator", "operator": "+" },
+      { "omdType": "number", "value": 1 }
+    ]
+  }
+}
+```
+
+**Renders as:** `f(x) = 2x + 1`
+
+---
+
+#### `omdTileEquation`
+
+Visual tile-based equations.
+
+**Schema:**
+```typescript
+{
+  left: Array<TileSpec>,
+  right: Array<TileSpec>,
+  equation?: string,
+  tileSize?: number,
+  tileGap?: number,
+  equalGap?: number,
+  tileRadius?: number,
+  showLabels?: boolean,
+  fontFamily?: string,
+  fontSize?: number,
+  plusColor?: string,
+  equalsColor?: string,
+  xPillColor?: string,
+  numberTileDefaults?: {
+    backgroundColor?: string,
+    dotColor?: string
+  }
+}
+```
+
+**Example:**
+```json
+{
+  "left": ["x", "x", 3],
+  "right": [11],
+  "equation": "2x + 3 = 11",
+  "tileSize": 28,
+  "tileGap": 6,
+  "showLabels": true,
+  "fontFamily": "Albert Sans",
+  "fontSize": 16
+}
+```
+
+---
+
+#### `omdProblem`
+
+Problem statement with associated visualization.
+
+**Schema:**
+```typescript
+{
+  problemText: string,
+  visualization: any
+}
+```
+
+**Example:**
+```json
+{
+  "problemText": "Solve for x:",
+  "visualization": {
+    "omdType": "equation",
+    "equation": "2x + 3 = 11"
+  }
+}
+```
+
+---
+
+## Usage Patterns
+
+### Loading from JSON
+
+All components follow the same pattern:
+
+```javascript
+const component = new ComponentClass();
+component.loadFromJSON(jsonData);
+```
+
+### String vs. Structured
+
+Many components accept both:
+
+```javascript
+// String form (simple)
+equation.loadFromJSON({ equation: '2x + 3 = 11' });
+
+// Structured form (programmatic)
+equation.loadFromJSON({
+  leftExpression: { termsAndOpers: [...] },
+  rightExpression: { termsAndOpers: [...] }
+});
+```
+
+### Nested Components
+
+Components can be nested:
+
+```javascript
+const plane = new omdCoordinatePlane();
+plane.loadFromJSON({
+  xMin: -10,
+  xMax: 10,
+  yMin: -10,
+  yMax: 10,
+  shapeSet: [
+    { omdType: 'circle', radius: 5, color: 'blue' },
+    { omdType: 'rectangle', width: 10, height: 5, color: 'red' }
+  ]
+});
+```
+
+---
+
+## Type Definitions
+
+For TypeScript users, the general pattern is:
+
+```typescript
+type Expression = string | {
+  termsAndOpers: Array<Term | Number | Variable | Operator>
+};
+
+type Term = {
+  omdType: 'term',
+  coefficient: number,
+  variable?: string,
+  exponent?: number
+};
+
+type Number = {
+  omdType: 'number',
+  value: number
+};
+
+type Variable = {
+  omdType: 'variable',
+  name: string
+};
+
+type Operator = {
+  omdType: 'operator',
+  operator: '+' | '-' | '/' | '÷' | 'x' | '*' | '•' | '×' | '='
+};
+```
+
+---
+
+## See Also
+
+- **[API Reference](./api/api-reference.md)** - Detailed API documentation
+- **[Getting Started](./guides/getting-started.md)** - Installation and basic usage
+- **[Visualizations Guide](./guides/visualizations.md)** - Visual component examples
+- **[Equations Guide](./guides/equations.md)** - Equation and expression examples