@mathscan/math-exercise-engine 1.0.1 → 1.0.3

package/README.md

@@ -15,26 +15,27 @@ A TypeScript DSL parser for mathematical exercises. Parse exercise definitions i
 ## 📦 Installation
 
 ```bash
-npm install math-exercise-engine
+npm install @mathscan/math-exercise-engine
 # or
-pnpm add math-exercise-engine
+pnpm add @mathscan/math-exercise-engine
 # or
-yarn add math-exercise-engine
+yarn add @mathscan/math-exercise-engine
 ```
 
 ## 🚀 Quick Start
 
 ```typescript
-import { compile, validate, ExerciseRenderer } from 'math-exercise-engine';
+import { compile, validate, ExerciseRenderer } from '@mathscan/math-exercise-engine';
 
 // Compile a DSL exercise to JSON
 const json = compile(`
-  COMPARISON[350158 ? 2334443, answer="<"]
+  QUESTION_TEXT["What is 25 + 5?"]
+  25 + NUMERIC_INPUT[name="x", digits=2, answer="5"] = 30
   WIDGET_ANSWER[type=simple]
 `);
 
 // Render in React
-import 'math-exercise-engine/style.css'; // Opt-in: import minimal default styles
+import '@mathscan/math-exercise-engine/style.css'; // Opt-in: import minimal default styles
 
 // Option 1: Use built-in submit button
 <ExerciseRenderer
@@ -88,7 +89,7 @@ const exerciseRef = useRef<ExerciseRendererRef>(null);
 When using `ref` for custom button styling, you get full programmatic control:
 
 ```typescript
-import type { ExerciseRendererRef } from 'math-exercise-engine';
+import type { ExerciseRendererRef } from '@mathscan/math-exercise-engine';
 
 const exerciseRef = useRef<ExerciseRendererRef>(null);
 
@@ -108,21 +109,37 @@ exerciseRef.current?.focusFirstInput();  // Focus first input field
 
 ## 📝 DSL Syntax
 
-### Numeric Input Widget
+### Input Widgets
+
+The DSL supports both legacy short names and modern readable aliases:
+
+#### Numeric Input Widget
 
 ```
 W_N_I[name=a, digits=2]
+// or use the readable alias
+NUMERIC_INPUT[name=a, digits=2]
 ```
 
 Creates an input field for numbers with up to 2 digits.
 
-### Comparison Widget
+#### String Input Widget
+
+```
+W_S_I[name=x, length=5]
+// or use the readable alias
+STRING_INPUT[name=x, length=5]
+```
+
+Creates an input field for text with up to 5 characters.
+
+### Text Highlighter
 
 ```
-COMPARISON[350158 ? 2334443, answer="<"]
+TEXT_HIGHLIGHTER[value="123456", start=2, end=3]
 ```
 
-Student must choose `<`, `>`, or `=` to compare two numbers.
+Displays text with specific characters highlighted (useful for highlighting digits in numbers).
 
 ### Validators
 
@@ -140,25 +157,27 @@ WIDGET_ANSWER[type=expression, expr="(a * b) + (c * d) == 1200"]
 
 ## 📚 Examples
 
-### Example 1: Simple Comparison
+### Example 1: Math Expression (using readable aliases)
 
 ```
-COMPARISON[350158 ? 2334443, answer="<"]
-WIDGET_ANSWER[type=simple]
+(NUMERIC_INPUT[name=a, digits=2] × NUMERIC_INPUT[name=b, digits=2]) + (NUMERIC_INPUT[name=c, digits=2] × NUMERIC_INPUT[name=d, digits=2]) = 1200
+WIDGET_ANSWER[type=expression, expr="(a * b) + (c * d) == 1200"]
 ```
 
-### Example 2: Math Expression
+### Example 2: Simple Addition
 
 ```
-(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"]
+NUMERIC_INPUT[name=x, digits=2] + NUMERIC_INPUT[name=y, digits=2] = 100
+WIDGET_ANSWER[type=expression, expr="x + y == 100"]
 ```
 
-### Example 3: Simple Addition
+### Example 3: Text Highlighter
 
 ```
-W_N_I[name=x, digits=2] + W_N_I[name=y, digits=2] = 100
-WIDGET_ANSWER[type=expression, expr="x + y == 100"]
+QUESTION_TEXT["What digit is highlighted?"]
+The number TEXT_HIGHLIGHTER[value="123456", start=2, end=3] has a highlighted digit
+STRING_INPUT[name=answer, length=1, answer="3"]
+WIDGET_ANSWER[type=simple]
 ```
 
 ## 🔧 API Reference
@@ -166,7 +185,7 @@ WIDGET_ANSWER[type=expression, expr="x + y == 100"]
 ### Parsing
 
 ```typescript
-import { compile, tokenize, parse, toAST, toJSON } from 'math-exercise-engine';
+import { compile, tokenize, parse, toAST, toJSON } from '@mathscan/math-exercise-engine';
 
 // Full pipeline (recommended)
 const json = compile(dslText);
@@ -184,7 +203,7 @@ const { ast, json } = compileWithAST(dslText);
 ### Validation
 
 ```typescript
-import { validate, validateSimple, validateExpression } from 'math-exercise-engine';
+import { validate, validateSimple, validateExpression } from '@mathscan/math-exercise-engine';
 
 // Auto-detect validation type
 const result = validate(exerciseJSON, userInputs);
@@ -203,7 +222,7 @@ import type {
   ValidationResult,
   WidgetJSON,
   ExerciseRendererRef
-} from 'math-exercise-engine';
+} from '@mathscan/math-exercise-engine';
 
 // ExerciseRendererRef interface:
 interface ExerciseRendererRef {
@@ -222,47 +241,43 @@ All layout items include unique `id` fields for React/JSX rendering:
 {
   "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" }
+    { "id": "text_1", "type": "text", "value": "25" },
+    { "id": "operator_2", "type": "operator", "operator": "+" },
+    { "id": "widget-ref_3", "type": "widget-ref", "widgetId": "x" },
+    { "id": "operator_4", "type": "operator", "operator": "=" },
+    { "id": "text_5", "type": "text", "value": "30" }
   ],
   "widgets": {
-    "comparison_1": {
-      "type": "comparison",
-      "id": "comparison_1",
+    "x": {
+      "type": "numeric-input",
+      "id": "x",
       "config": {
-        "left": 350158,
-        "right": 2334443
+        "name": "x",
+        "digits": 2
       }
     }
   },
   "validation": {
     "mode": "simple",
     "answers": {
-      "comparison_1": "<"
+      "x": "5"
     }
   }
 }
 ```
 
-> 💡 **New:** Layout items now include unique IDs perfect for React keys. [Learn more](docs/LAYOUT_IDS.md)
-
 ## ✅ Testing
 
 ```bash
-pnpm test
+pnpm test:run
 ```
 
-All 83 tests passing ✅
-
 ## 📄 License
 
-[Your License]
+mathscan
 
 ## 👥 Authors
 
-[Your Name]
+mathscan
 
 ---
-
-**Status**: Production ready. All tests passing.