@mathscan/math-exercise-engine 1.0.0

package/README.md

@@ -0,0 +1,268 @@
+# Math Exercise Engine
+
+A TypeScript DSL parser for mathematical exercises. Parse exercise definitions into structured AST and JSON for use in educational apps.
+
+## ✨ Features
+
+- **Text-first DSL** — Write exercises in readable text format
+- **Chevrotain parser** — Robust tokenization and parsing
+- **AST-based** — Clean separation between parsing and rendering
+- **Dual validation** — Simple (predetermined answers) and expression-based
+- **TypeScript-first** — Full type definitions included
+- **React renderer** — Production-ready components included
+- **Ref-based API** — Full programmatic control (submit, reset, focus, get values)
+
+## 📦 Installation
+
+```bash
+npm install math-exercise-engine
+# or
+pnpm add math-exercise-engine
+# or
+yarn add math-exercise-engine
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { compile, validate, ExerciseRenderer } from 'math-exercise-engine';
+
+// Compile a DSL exercise to JSON
+const json = compile(`
+  COMPARISON[350158 ? 2334443, answer="<"]
+  WIDGET_ANSWER[type=simple]
+`);
+
+// Render in React
+import 'math-exercise-engine/style.css'; // Opt-in: import minimal default styles
+
+// Option 1: Use built-in submit button
+<ExerciseRenderer
+  json={json}
+  onSubmit={(values) => {
+    const result = validate(json, values);
+    console.log(result.isCorrect);
+  }}
+  showSubmitButton={true}
+/>
+
+// Option 2: Control submit with ref (recommended for custom styling)
+const exerciseRef = useRef<ExerciseRendererRef>(null);
+
+<ExerciseRenderer
+  ref={exerciseRef}
+  json={json}
+  onSubmit={(values) => {
+    const result = validate(json, values);
+    console.log(result.isCorrect);
+  }}
+/>
+
+// Custom buttons (fully controlled by your app)
+<div>
+  <button
+    className="my-custom-submit-btn"
+    onClick={() => {
+      const result = exerciseRef.current?.submit();
+      console.log('Validation result:', result);
+      if (result?.isCorrect) {
+        alert('Correct! 🎉');
+      } else {
+        alert('Try again! ❌');
+      }
+    }}
+  >
+    Check My Answer
+  </button>
+  <button onClick={() => exerciseRef.current?.reset()}>
+    Reset Exercise
+  </button>
+  <button onClick={() => exerciseRef.current?.focusFirstInput()}>
+    Focus First Input
+  </button>
+</div>
+```
+
+## 🎛️ Ref API - Programmatic Control
+
+When using `ref` for custom button styling, you get full programmatic control:
+
+```typescript
+import type { ExerciseRendererRef } from 'math-exercise-engine';
+
+const exerciseRef = useRef<ExerciseRendererRef>(null);
+
+// Available methods:
+const result = exerciseRef.current?.submit();    // Returns ValidationResult
+exerciseRef.current?.getValues();        // Get current input values
+exerciseRef.current?.reset();            // Clear all inputs
+exerciseRef.current?.focusFirstInput();  // Focus first input field
+```
+
+### Method Details
+
+- **`submit()`**: Performs validation and returns `ValidationResult` (also triggers `onSubmit` callback)
+- **`getValues()`**: Returns `Record<string, string>` of all current input values
+- **`reset()`**: Clears all input fields to empty state
+- **`focusFirstInput()`**: Automatically focuses the first input element
+
+## 📝 DSL Syntax
+
+### Numeric Input Widget
+
+```
+W_N_I[name=a, digits=2]
+```
+
+Creates an input field for numbers with up to 2 digits.
+
+### Comparison Widget
+
+```
+COMPARISON[350158 ? 2334443, answer="<"]
+```
+
+Student must choose `<`, `>`, or `=` to compare two numbers.
+
+### Validators
+
+**Simple mode** — each widget has a predetermined answer:
+
+```
+WIDGET_ANSWER[type=simple]
+```
+
+**Expression mode** — validate using a math expression:
+
+```
+WIDGET_ANSWER[type=expression, expr="(a * b) + (c * d) == 1200"]
+```
+
+## 📚 Examples
+
+### Example 1: Simple Comparison
+
+```
+COMPARISON[350158 ? 2334443, answer="<"]
+WIDGET_ANSWER[type=simple]
+```
+
+### Example 2: Math Expression
+
+```
+(W_N_I[name=a, digits=2] × W_N_I[name=b, digits=2]) + (W_N_I[name=c, digits=2] × W_N_I[name=d, digits=2]) = 1200
+WIDGET_ANSWER[type=expression, expr="(a * b) + (c * d) == 1200"]
+```
+
+### Example 3: Simple Addition
+
+```
+W_N_I[name=x, digits=2] + W_N_I[name=y, digits=2] = 100
+WIDGET_ANSWER[type=expression, expr="x + y == 100"]
+```
+
+## 🔧 API Reference
+
+### Parsing
+
+```typescript
+import { compile, tokenize, parse, toAST, toJSON } from 'math-exercise-engine';
+
+// Full pipeline (recommended)
+const json = compile(dslText);
+
+// Step by step
+const tokens = tokenize(dslText);
+const cst = parse(tokens);
+const ast = toAST(cst);
+const json = toJSON(ast);
+
+// With both AST and JSON
+const { ast, json } = compileWithAST(dslText);
+```
+
+### Validation
+
+```typescript
+import { validate, validateSimple, validateExpression } from 'math-exercise-engine';
+
+// Auto-detect validation type
+const result = validate(exerciseJSON, userInputs);
+
+// Manual validation
+const simpleResult = validateSimple(exerciseJSON, userInputs);
+const exprResult = validateExpression(exerciseJSON, userInputs);
+```
+
+### Types
+
+```typescript
+import type {
+  ExerciseJSON,
+  ExerciseNode,
+  ValidationResult,
+  WidgetJSON,
+  ExerciseRendererRef
+} from 'math-exercise-engine';
+
+// ExerciseRendererRef interface:
+interface ExerciseRendererRef {
+  submit: () => ValidationResult;        // Perform validation & return result
+  getValues: () => Record<string, string>; // Get current values
+  reset: () => void;                     // Clear all inputs
+  focusFirstInput: () => void;           // Focus first input
+}
+```
+
+## 📊 JSON Output Format
+
+All layout items include unique `id` fields for React/JSX rendering:
+
+```json
+{
+  "version": "2.0",
+  "layout": [
+    { "id": "text_1", "type": "text", "value": "350158" },
+    { "id": "widget-ref_2", "type": "widget-ref", "widgetId": "comparison_1" },
+    { "id": "text_3", "type": "text", "value": "2334443" }
+  ],
+  "widgets": {
+    "comparison_1": {
+      "type": "comparison",
+      "id": "comparison_1",
+      "config": {
+        "left": 350158,
+        "right": 2334443
+      }
+    }
+  },
+  "validation": {
+    "mode": "simple",
+    "answers": {
+      "comparison_1": "<"
+    }
+  }
+}
+```
+
+> 💡 **New:** Layout items now include unique IDs perfect for React keys. [Learn more](docs/LAYOUT_IDS.md)
+
+## ✅ Testing
+
+```bash
+pnpm test
+```
+
+All 83 tests passing ✅
+
+## 📄 License
+
+[Your License]
+
+## 👥 Authors
+
+[Your Name]
+
+---
+
+**Status**: Production ready. All tests passing.