@mathscan/math-exercise-engine 1.0.1 → 1.0.2

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", "value": "+" },
+    { "id": "widget-ref_3", "type": "widget-ref", "widgetId": "x" },
+    { "id": "operator_4", "type": "operator", "value": "=" },
+    { "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.

package/dist/index.d.ts

@@ -137,11 +137,6 @@ export declare function createExpressionValidation(expression: string): Expressi
  */
 export declare function createFreeText(value: string): FreeTextInline;
 
-/**
- * @deprecated Use createStringInput or createNumericInput instead
- */
-export declare function createInlineInput(name: string, inputType: "string" | "numeric", lengthOrDigits: number, answer?: string | number): InlineInputWidget;
-
 /**
  * Create a line block
  */
@@ -1025,13 +1020,6 @@ export declare function isNumberText(item: LayoutItem): item is Extract<LayoutIt
     type: 'number-text';
 }>;
 
-/**
- * @deprecated Use isInlineInputJSON instead
- */
-export declare function isNumericInputJSON(widget: WidgetJSON): widget is Extract<WidgetJSON, {
-    type: 'inline-input';
-}>;
-
 export declare function isNumericKeypad(value: unknown): value is NumericKeypadTool;
 
 /**
@@ -1080,13 +1068,6 @@ export declare function isValidationNode(value: unknown): value is ValidationNod
  */
 export declare function isValidExpression(expression: string): boolean;
 
-/**
- * @deprecated Use isWidgetRef instead
- */
-export declare function isWidgetPlaceholder(item: LayoutItem): item is Extract<LayoutItem, {
-    type: 'widget-ref';
-}>;
-
 /**
  * Type guard for WidgetRef
  */
@@ -1975,9 +1956,7 @@ export declare const WidgetJSONSchema: z.ZodUnion<[z.ZodDiscriminatedUnion<"inpu
     includeDecimal: boolean;
 }>]>;
 
-declare type WidgetRef = z.infer<typeof WidgetRefSchema>;
-export { WidgetRef as WidgetPlaceholder }
-export { WidgetRef }
+export declare type WidgetRef = z.infer<typeof WidgetRefSchema>;
 
 export declare const WidgetRefSchema: z.ZodObject<{
     id: z.ZodString;

package/dist/index.js

@@ -31,14 +31,18 @@ const QUESTION_TEXT = chevrotain.createToken({
   name: "QUESTION_TEXT",
   pattern: /QUESTION_TEXT/
 });
-const NUMBER_TEXT = chevrotain.createToken({
-  name: "NUMBER_TEXT",
-  pattern: /NUMBER_TEXT/
+const TEXT_HIGHLIGHTER = chevrotain.createToken({
+  name: "TEXT_HIGHLIGHTER",
+  pattern: /TEXT_HIGHLIGHTER/
 });
 const W_S_I = chevrotain.createToken({
   name: "W_S_I",
   pattern: /W_S_I/
 });
+const STRING_INPUT = chevrotain.createToken({
+  name: "STRING_INPUT",
+  pattern: /STRING_INPUT/
+});
 const DRAGABLE_BUTTONS_OPTIONS = chevrotain.createToken({
   name: "DRAGABLE_BUTTONS_OPTIONS",
   pattern: /DRAGABLE_BUTTONS_OPTIONS/
@@ -55,6 +59,10 @@ const W_N_I = chevrotain.createToken({
   name: "W_N_I",
   pattern: /W_N_I/
 });
+const NUMERIC_INPUT = chevrotain.createToken({
+  name: "NUMERIC_INPUT",
+  pattern: /NUMERIC_INPUT/
+});
 const NumberLiteral = chevrotain.createToken({
   name: "NumberLiteral",
   pattern: /-?\d+(\.\d+)?/
@@ -137,13 +145,14 @@ const allTokens = [
   Comment,
   // Component keywords (before Identifier!)
   QUESTION_TEXT,
-  NUMBER_TEXT,
+  TEXT_HIGHLIGHTER,
   W_S_I,
+  STRING_INPUT,
   DRAGABLE_BUTTONS_OPTIONS,
   NUMERIC_KEYPAD,
   WIDGET_ANSWER,
-  // Legacy keywords
   W_N_I,
+  NUMERIC_INPUT,
   // Literals
   NumberLiteral,
   StringLiteral,
@@ -321,14 +330,14 @@ class MathExerciseParser extends chevrotain.CstParser {
         // Parentheses (for grouping)
         { ALT: () => this.CONSUME(LParen) },
         { ALT: () => this.CONSUME(RParen) },
-        // NUMBER_TEXT (for highlighting)
-        { ALT: () => this.SUBRULE(this.numberText) },
+        // TEXT_HIGHLIGHTER (for highlighting)
+        { ALT: () => this.SUBRULE(this.textHighlighter) },
         // W_S_I (inline input widget)
         { ALT: () => this.SUBRULE(this.inlineInput) }
       ]);
     });
-    this.numberText = this.RULE("numberText", () => {
-      this.CONSUME(NUMBER_TEXT);
+    this.textHighlighter = this.RULE("textHighlighter", () => {
+      this.CONSUME(TEXT_HIGHLIGHTER);
       this.CONSUME(LBracket);
       this.SUBRULE(this.parameterList);
       this.CONSUME(RBracket);
@@ -336,7 +345,9 @@ class MathExerciseParser extends chevrotain.CstParser {
     this.inlineInput = this.RULE("inlineInput", () => {
       this.OR([
         { ALT: () => this.CONSUME(W_S_I, { LABEL: "stringInput" }) },
-        { ALT: () => this.CONSUME(W_N_I, { LABEL: "numericInput" }) }
+        { ALT: () => this.CONSUME(STRING_INPUT, { LABEL: "stringInput" }) },
+        { ALT: () => this.CONSUME(W_N_I, { LABEL: "numericInput" }) },
+        { ALT: () => this.CONSUME(NUMERIC_INPUT, { LABEL: "numericInput" }) }
       ]);
       this.CONSUME(LBracket);
       this.SUBRULE(this.parameterList);
@@ -529,13 +540,6 @@ function createNumericInput(name, digits, answer) {
     answer
   });
 }
-function createInlineInput(name, inputType, lengthOrDigits, answer) {
-  if (inputType === "string") {
-    return createStringInput(name, lengthOrDigits, answer);
-  } else {
-    return createNumericInput(name, lengthOrDigits, answer);
-  }
-}
 function isFreeText(value) {
   return FreeTextInlineSchema.safeParse(value).success;
 }
@@ -754,18 +758,21 @@ class NaturalDSLVisitor extends BaseCstVisitor {
       const token = ctx.RParen[0];
       return createFreeText(token.image);
     }
-    if (ctx.numberText) {
-      return this.visit(ctx.numberText);
+    if (ctx.textHighlighter) {
+      return this.visit(ctx.textHighlighter);
     }
     if (ctx.inlineInput) {
       return this.visit(ctx.inlineInput);
     }
     throw new Error("Unknown inline element");
   }
-  numberText(ctx) {
+  textHighlighter(ctx) {
     const params = this.visit(ctx.parameterList);
     const value = params.value;
-    const highlight = params.highlight;
+    let highlight = void 0;
+    if (params.start !== void 0 && params.end !== void 0) {
+      highlight = [params.start, params.end];
+    }
     return createNumberText(value, highlight);
   }
   inlineInput(ctx) {
@@ -1024,12 +1031,6 @@ function isDragOptionsJSON(widget) {
 function isNumericKeypadJSON(widget) {
   return widget.type === "numeric-keypad";
 }
-function isWidgetPlaceholder(item) {
-  return item.type === "widget-ref";
-}
-function isNumericInputJSON(widget) {
-  return widget.type === "inline-input";
-}
 class LayoutIdGenerator {
   constructor() {
     this.counter = 0;
@@ -5745,7 +5746,7 @@ const LayoutRenderer = ({
         const [start, end] = item.highlight;
         return /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "number-text", children: [
           item.value.slice(0, start),
-          /* @__PURE__ */ jsxRuntime.jsx("mark", { className: "highlight", children: item.value.slice(start, end) }),
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "highlight", children: item.value.slice(start, end) }),
           item.value.slice(end)
         ] });
       }
@@ -6025,7 +6026,6 @@ exports.createDragOptions = createDragOptions;
 exports.createExerciseDocument = createExerciseDocument;
 exports.createExpressionValidation = createExpressionValidation;
 exports.createFreeText = createFreeText;
-exports.createInlineInput = createInlineInput;
 exports.createLineBlock = createLineBlock;
 exports.createNumberText = createNumberText;
 exports.createNumericInput = createNumericInput;
@@ -6050,7 +6050,6 @@ exports.isInlineNode = isInlineNode;
 exports.isLineBlock = isLineBlock;
 exports.isLinebreak = isLinebreak;
 exports.isNumberText = isNumberText;
-exports.isNumericInputJSON = isNumericInputJSON;
 exports.isNumericKeypad = isNumericKeypad;
 exports.isNumericKeypadJSON = isNumericKeypadJSON;
 exports.isOperatorItem = isOperatorItem;
@@ -6062,7 +6061,6 @@ exports.isTextItem = isTextItem;
 exports.isToolNode = isToolNode;
 exports.isValidExpression = isValidExpression;
 exports.isValidationNode = isValidationNode;
-exports.isWidgetPlaceholder = isWidgetPlaceholder;
 exports.isWidgetRef = isWidgetRef;
 exports.parse = parse;
 exports.parseSafe = parseSafe;